It's a simple library providing just a single function that returns requested BGG data as a JavaScript object. It uses ofetch and fast-xml-parser under the hood.

import { bggXmlApiClient } from 'bgg-xml-api-client' const response = await bggXmlApiClient.get('user', { name: 'Qrzy88' }) console.log(response.id) // displays: 1381959

bggXmlApiClient takes 3 parameters:

• BGG API resource name
• resource parameters as object - for better DX the parameters are typed, but the type is a union of types given to the wrappers listed below
• client options with required authorizationKey (as of fall 2025)

There are also wrappers available for certain resources that accept params (already typed) and settings that serve as options for the basic client:

• getBggCollection(param, settings)
• getBggFamily(params, settings)
• getBggForum(params, settings)
• getBggForumlist(params, settings)
• getBggGeeklist(params, settings)
• getBggGuild(params, settings)
• getBggHot(params, settings)
• getBggPlays(params, settings)
• getBggSearch(params, settings)
• getBggThing(params, settings)
• getBggThread(params, settings)
• getBggUser(params, settings)

Both main client as well as wrappers accept one more parameter that can override default options:

interface ClientOptions { authorizationKey: string maxRetries?: number // default 10 retryInterval?: number // default 5000[ms] (5s) timeout?: number // default 10000[ms] (10s) }

The authorizationKey is the bare minimum as of fall 2025 - BGG rquires all requests to their XML APIs to have proper authorization header. You can find more at Using the XML API -> Application Tokens

One can use it to control the retry flow when collections API replies with 202 status code meaning the request is still processing and one should retry later for actual results.

For example, in order to increase number of retries on 202 response to 20 made in an interval of 3s:

import { bggXmlApiClient } from 'bgg-xml-api-client' const response = await bggXmlApiClient.get('collection', { username: 'Qrzy88' }, { authorizationKey: 'THEKEY', maxRetries: 20, retryInterval: 3000 })

or to reduce the timeout to 5s when fetching user:

import { getBggUser } from 'bgg-xml-api-client' const response = await getBggUser({ name: 'Qrzy88' }, { authorizationKey: 'THEKEY', timeout: 5000 })