A TypeScript client for working with the BoardGameGeek.com API.
To use bgg-client, you must get an API key, and accept BoardGameGeek.com's XML API Terms of Use.
# npm
npm install bgg-client
# pnpm
pnpm add bgg-client
# yarn
yarn add bgg-client
# bun
bun add bgg-clientImport the BoardGameGeekClient class, and create a new instance of it with an API key.
import { BoardGameGeekClient } from 'bgg-client';
const bgg = new BoardGameGeekClient('your-api-key');By default, there is a rate limit of 1 request every 5 seconds to comply with the BoardGameGeek API's suggested request rate.
For full manual access to any endpoint, you can use the lower-level ApiClient class. However, this is not fully supported, and you may have to provide your own types for full type safety.
The default export has been removed. You must now import BoardGameGeekClient and provide an API key, as described above.
search(query, options)
Calls the search endpoint to look up games by name. Returns an array of matching items, including board games, expansions, and other types. Supports options like type and exact.
thing(id, options)
Calls the thing endpoint to fetch detailed information about a game or item by its BGG ID. Supports options like stats to include game statistics.
hot(options)
Calls the hot endpoint to retrieve a list of trending or popular items. You can optionally specify a type (e.g., boardgame, rpg, boardgameperson) to filter results.
family(id, options)
Calls the family endpoint to retrieve a "family", and an array of links to related things. You can optionally specify a type (e.g., boardgamefamily, rpg, rpgperiodical) to filter results.
user(name, options)
Calls the user endpoint to retrieve a "user" by their username, and their related stats. You can optionally include "buddies", "guilds", as well as the user's "top" and "hot" items
user(id, options)
Calls the guild endpoint to retrieve a "guild" by id. You can optionally include a list of users that belong to the guild.
plays(id, options)
Calls the plays endpoint to retrieve a list of "plays" by the id of a "thing" or "user".
user(username, options)
Calls the collection endpoint to retrieve a users collection by their username. Can be filtered using various options detailed here.
forumList(id, options)
Calls the "forumlist" endpoint to retrieve a list of "forums" for a given "thing" by the thing id.
forum(id, options)
Calls the "forum" endpoint to retrieve a "forum", or list of "threads", by forum id.
thread(id, options)
Calls the "thread" endpoint to retrieve a forum "thread" by thread id.
import { BoardGameGeekClient } from 'bgg-client';
const bgg = new BoardGameGeekClient('your-api-key');
try {
const results = await bgg.search('Cascadia');
const game = await bgg.thing(342942); // Cascadia's BGG ID
const hot = await bgg.hot();
} catch {
// handle the error
}Refer to the BGG XML API2 docs for documentation on all endpoints, and their options.