bgg-api-ts

A TypeScript wrapper for the BoardGameGeek XML API v2. The BGG API speaks XML; this library handles that and gives you typed objects back.

Installation

npm install bgg-api-ts

Requirements

BGG requires an API token as of 2025. Register an application, then generate a token from your application page.

Do not make requests from a browser. Your token will be exposed. Run this server-side.

Quick Start

import { BggClient } from "bgg-api-ts";

const client = new BggClient("https://boardgamegeek.com/xmlapi2/", "your-api-token");

const result = await client.getThing(174430, { stats: true });
const game = result.items.item[0];

console.log(game.name[0].value); // "Gloomhaven"
console.log(game.statistics?.ratings.average.value); // 8.4

Authentication

Pass your token as the second argument to BggClient:

const client = new BggClient("https://boardgamegeek.com/xmlapi2/", process.env.BGG_TOKEN);

The token is sent as a Bearer header on every request. See the Installation & Auth wiki page for setup steps.

Rate Limiting

The client waits at least 5 seconds between requests automatically. You do not need to manage this yourself. Sending requests faster than that causes BGG to return 500 or 503 errors.

Error Handling

Two error types are thrown:

• BggError: HTTP errors (401, 403, 429, 500, 503). Has a statusCode property.
• BggTimeoutError: The request took longer than 30 seconds, or the server returned HTTP 202 (queued) more than 5 times in a row.

import { BggClient, BggError, BggTimeoutError } from "bgg-api-ts";

try {
  const result = await client.getCollection({ username: "someuser", own: true });
} catch (err) {
  if (err instanceof BggTimeoutError) {
    // BGG queued the request and never finished processing it
    console.error("Timed out:", err.message);
  } else if (err instanceof BggError) {
    // HTTP error from BGG
    console.error(`HTTP ${err.statusCode}:`, err.message);
  }
}

HTTP 202 is specific to the collection endpoint. BGG queues those requests when the data is not cached. The client retries up to 5 times before giving up.

Examples

Fetch a game with stats

const result = await client.getThing(174430, { stats: true });
const game = result.items.item[0];

console.log(game.name[0].value); // "Gloomhaven"
console.log(game.statistics?.ratings.ranks.rank[0].value); // 1

Fetch multiple games at once

const result = await client.getThing([174430, 161936, 167791]);

for (const item of result.items.item) {
  console.log(item.id, item.name[0].value);
}

Search for a game

const result = await client.search({ query: "Catan", type: "boardgame", exact: true });
const id = result.items.item?.[0].id; // 13

Get a user's owned games

const result = await client.getCollection({ username: "Blxckmage", own: true, stats: true });

console.log(result.items.totalitems); // number of owned games
for (const item of result.items.item ?? []) {
  console.log(item.name[0].value);
}

Get play history

const result = await client.getPlays({ username: "Blxckmage", mindate: "2025-01-01" });

console.log(result.plays.total); // total plays logged
for (const play of result.plays.play ?? []) {
  console.log(play.date, play.item[0].name);
}

Get the hot list

const result = await client.getHot("boardgame");

for (const item of result.items.item) {
  console.log(item.rank, item.name?.value);
}

API Reference

Full parameter and response type documentation is on the GitHub Wiki.

| Method | Description | |---|---| | getThing(ids, options?) | Fetch games, expansions, or accessories by ID | | getFamily(ids, type?) | Fetch game family groups by ID | | getHot(type) | Fetch the current hot list for a category | | search(options) | Search by name | | getUser(options) | Fetch a user profile | | getCollection(options) | Fetch a user's game collection | | getPlays(options?) | Fetch play history |

Terms of Use

This library accesses the BGG XML API. Use of the API is subject to the BGG XML API Terms of Use:

• Non-commercial use only, unless you have a license from BGG.
• Data from the API cannot be used to train AI or LLM systems.
• You must credit BoardGameGeek by name and include a "Powered by BGG" logo where applicable.
• You must link back to BoardGameGeek.

License

MIT