boardgamegeekclient

A wrapper around the official BoardGameGeek V2 API, designed to provide a more convenient way to work with their XML-based endpoints. The package now supports the required authorization and can be used to build web apps or integrate backend services.

Key features

• :ballot_box_with_check: Support Authorization via BGG tokens
• :ballot_box_with_check: Fully typed requests and responses
• :ballot_box_with_check: Easy to use
• :ballot_box_with_check: Typescript written
• :ballot_box_with_check: Promisified
• :ballot_box_with_check: thing, family, forum, thread, user, guild, play, collection endpoints

Prerequisites

Starting in Fall 2025, BoardGameGeek requires all API clients to use authorization.
Before using this package, you must register your application on BoardGameGeek and obtain an access token.

Register and manage your application here: https://boardgamegeek.com/applications

Installation

npm i boardgamegeekclient

yarn add boardgamegeekclient

Usage

In Node.js (commonjs) environment

const { BggClient } = require("boardgamegeekclient");

In ES environment

import { BggClient } from 'boardgamegeekclient';

Initialize BggClient and get singleton instance

const client = BggClient.Create({ apiKey: 'YOUR_API_KEY' });

API

Interact with boardgamegeek entities using the corresponding client object and fire a request with query or queryWithProgress method.

Thing

Get boardgame, boardgame expansion, boardgame accessory, videogame, rpgitem, rpgissue informations.
Thing client expose query and queryWithProgress.

Examples

const things: BggThingDto[] = await client.thing.query({ id: [174430, 35421], 
                                                         videos: 1,
                                                         comments: 1,
                                                         marketplace: 1,
                                                         stats: 1,
                                                         type: "boardgame" });

// with progress handler as parameter

await client.thing.queryWithProgress({
                id: [250621, 257668, 226255, 340790, 279307, 279306, 345121, 271447, 187104, 253618, 271512, 432, 68448, 173346, 346703, 302260, 239472, 172818, 231398, 202408, 267814, 267813, 191189, 267127, 281946, 264647, 2272, 230085, 31260, 247367, 256442, 161970, 6249, 181293],
                videos: 1,
                comments: 1,
                marketplace: 1,
                stats: 1,
                type: "boardgame"
            }, { limit: 10 }, _data => {
                
            });

// with progress handler registered on the client itself

client.thing.progressHandler = (_data) => { };

await client.thing.queryWithProgress({
    id: [250621, 257668, 226255, 340790, 279307, 279306, 345121, 271447, 187104, 253618, 271512, 432, 68448, 173346, 346703, 302260, 239472, 172818, 231398, 202408, 267814, 267813, 191189, 267127, 281946, 264647, 2272, 230085, 31260, 247367, 256442, 161970, 6249, 181293],
    videos: 1,
    comments: 1,
    marketplace: 1,
    stats: 1,
    type: "boardgame"
}, { limit: 10 });

Family

Get rpg, rpgperiodical, boardgamefamily informations.
Family client expose query and queryWithProgress.

Examples

const families = await client.family.query({ id: [174430, 35421] });

Forum List

Get a list of forums
(in boardgame or family page (of the id), forums tab, left sidebars with all forums).
ForumList client expose query and queryWithProgress.

Examples

const forumlists: BggForumlistDto[] = await client.forumlist.query({ id: [8374,22184,59218,1029,2076], type: ['family']});

Forum

Get a single forum.

Examples

const forum = await client.forum.query({ id: 19, page: 3 });

Thread

Get a single thread.

Examples

const threads: BggThreadDto[] = await client.thread.query({ id: 2571698, minarticledate: '2021-01-03', count: 15 });

User

Get public profile information about a user by username.

Examples

const users: BggUserDto[] = await client.user.query({ name: 'mattiabanned', hot: 1, top: 1 });

Guild

Get a single guild.

Examples

const guilds: BggGuildDto[] = await client.guild.query({ id: 1000, members: 1, sort: 'date', page: 1 });

Play

Request plays logged by a particular user or for a particular item.

Examples

const plays: BggPlayDto[] = await client.play.query({ username: 'mattiabanned' });

Collection

Examples

const collections: BggCollectionDto[]  = await client.collection.query({ username: 'mattiabanned', excludesubtype: ["boardgameaccessory"] });