RonanCodes/boardgamegeek

BoardGameGeek XML API2

BoardGameGeek (BGG) is the canonical database for board games: every game has a numeric id, community ratings, complexity weight, player-count polls, and box art. BGG exposes this over the XML API2 at https://boardgamegeek.com/xmlapi2/. Responses are XML; this skill ships a stdlib-only Python client (scripts/bgg.py) that converts them to clean JSON.

The one thing to know before anything else: since 2026 every XML API endpoint returns 401 Unauthorized without a registered application token. That includes /thing, /search, /collection, /hot, and the legacy /xmlapi. There is no anonymous API access anymore. Facts below verified 2026-07-03.

Auth model and registration walkthrough

1. Go to https://boardgamegeek.com/applications and use the "Apply to use the XML API" form (it lives at /applications/create). Describe the application and whether it is commercial.
2. Wait. Approval takes a week or more. There is no instant self-serve token.
3. Once approved, return to https://boardgamegeek.com/applications and open "Tokens" next to the application to create a token.
4. Send it on every request as Authorization: Bearer <token> (the word "Bearer", one space, the token; no colon). Tokens currently do not expire and there is no refresh flow.
5. Use the base domain https://boardgamegeek.com WITHOUT a leading www, or auth fails.

Current state for Ronan: an application named "Oostenburg Board Game Club Tools" (non-commercial) was submitted on 2026-07-03 and is pending approval. Until it lands, API calls return 401 and the browser fallback below is the working path.

Documented exceptions to registration: downloading YOUR OWN collection while logged in on the site needs no registration; fetching other users' collections while logged in works but is heavily rate limited.

Usage monitoring once live: https://boardgamegeek.com/applications, "Usage" under the application.

Token setup

Store the token in the shared env file ~/.claude/.env (section headers per plugin, one file):

# --- BoardGameGeek ---
BGG_XML_API_TOKEN=<token from boardgamegeek.com/applications>

scripts/bgg.py reads it from there (tolerates quotes, comments, and export prefixes). If the key is unset or the API answers 401, the script prints the pending-registration explanation and exits 2. That is expected behaviour until approval.

Auth decision flow

flowchart TD
  A["Need BGG data"] --> B{"BGG_XML_API_TOKEN<br/>in ~/.claude/.env?"}
  B -- yes --> C["scripts/bgg.py<br/>XML API2 + Bearer header"]
  C --> D{"HTTP status"}
  D -- 200 --> E["JSON out"]
  D -- 202 (collection queued) --> F["retry 2s, 5s, 10s"] --> C
  D -- 401 --> G["token invalid or app<br/>still pending approval"]
  B -- no --> G
  G --> H["Browser fallback:<br/>GEEK.geekitemPreload JSON<br/>(own/public data only)"]
  A -.box art only.-> I["cf.geekdo-images.com<br/>plain curl + browser UA,<br/>no auth needed"]

Endpoint reference

Base: https://boardgamegeek.com/xmlapi2/. All return XML.

| Endpoint | What it gives | Notes | |---|---|---| | /thing?id=<comma-separated-ids>&stats=1 | Game details: name, yearpublished, minplayers/maxplayers, playingtime, image + thumbnail URLs; with stats=1 also ratings average, averageweight (complexity), ranks | Batch ids in one call; keep batches modest (~20) | | /search?query=<q>&type=boardgame | Name search returning ids | Add &exact=1 for exact-name match | | /collection?username=<u>&own=1&stats=1 | A user's collection | See the 202 contract below. Other flags: wishlist=1, want=1, played=1, subtype=boardgame, excludesubtype=boardgameexpansion | | /hot?type=boardgame | Current hotness list | | | /user?name=<u> | User profile | | | /plays?username=<u> | Logged plays | Paged |

The 202-retry contract on /collection: the first request for a collection usually returns HTTP 202 with an empty-ish body, meaning "queued, come back". Retry the same URL with backoff (2s, 5s, 10s) until it returns 200 with the real payload. scripts/bgg.py does this automatically.

Rate limits and caching

• Keep it gentle: about one request per 2 seconds. The script sleeps between batched /thing calls.
• Cache responses on disk. Game data changes slowly; a day-old /thing response is fine for almost everything.
• Make requests server-side (CLI, backend), not from user browsers, so the token never ships to a client.

The bundled script

Run from the skill directory (or use the full path to scripts/bgg.py):

python3 scripts/bgg.py search "brass birmingham"
python3 scripts/bgg.py thing 224517 167791 --stats
python3 scripts/bgg.py collection <username> --own --stats --exclude-expansions
python3 scripts/bgg.py hot
python3 scripts/bgg.py image 224517 --out ./boxart

Output is pretty JSON. thing items carry: id, name, year, players.min/max, playingtime, rating.average, rating.weight, rating.rank, image, thumbnail. Exit codes: 0 ok, 1 API or parse error, 2 auth (401, registration pending).

Browser fallback (until the token arrives)

BGG game pages and public collection/wishlist pages render without login and embed the full item JSON in the HTML as GEEK.geekitemPreload. Plain curl gets a Cloudflare 403; a real browser (Playwright MCP or Claude in Chrome) passes. Verified working 2026-07-03.

Recipe:

1. Navigate the browser to any boardgamegeek.com page (establishes the Cloudflare clearance).
2. In page context, batch fetch() calls to the game page URLs with 400 to 500ms delays between them.
3. Parse GEEK.geekitemPreload out of each response body. Useful fields: item.name, yearpublished, minplayers, maxplayers, minplaytime, maxplaytime, stats.average, stats.avgweight, rankinfo[0].rank, polls.userplayers.best / recommended, imageurl, images.original.

For collection pages, the HTML itself is the data: rows match #collectionitems tr[id^="row_"], the game link is td.collection_objectname a (its href contains /boardgame/<id>/), the user rating is .collection_rating .ratingtext, and ownership status is td.collection_status.

This is a stopgap for your own or public data, not a substitute for registering.

Image downloads

The image CDN cf.geekdo-images.com is NOT auth-gated. Plain curl with a browser User-Agent downloads box art fine, token or no token. Convention: python3 scripts/bgg.py image <id> --out <dir> resolves the image URL via /thing, then saves to <dir>/<id>-<slug>.jpg (slug from the game name). If the API is still 401, take imageurl / images.original from the browser fallback and curl it directly with -A "Mozilla/5.0 ...".

Policy and attribution

• Public-facing artefacts built on BGG data must show the "Powered by BGG" logo linking back to https://boardgamegeek.com.
• Per BGG's third-party library policy, anyone else using this open-source skill must register their OWN application and token; tokens are per-application, not shareable.
• Scripts stick to the documented XML API2 and public pages. No BGG "private" site APIs.

Common flows

Fetch a collection into JSON:

python3 scripts/bgg.py collection <username> --own --stats > collection.json

The script handles the 202 queue-retry. Add --wishlist for wishlist items, --exclude-expansions to drop expansions.

Resolve a list of game names to ids + stats:

python3 scripts/bgg.py search "ark nova"           # take the id from the results
python3 scripts/bgg.py thing 342942 --stats        # full details, batched ids fine

For many names, search each (2s apart), collect ids, then one batched thing --stats call.

Cache box art locally:

for id in 224517 342942 167791; do
  python3 scripts/bgg.py image "$id" --out ./boxart
  sleep 2
done

Further reading

• XML API2 documentation: https://boardgamegeek.com/wiki/page/BGG_XML_API2
• Application registration and tokens: https://boardgamegeek.com/applications
• API terms of use: https://boardgamegeek.com/wiki/page/XML_API_Terms_of_Use
• Legacy XML API (v1) reference: https://boardgamegeek.com/wiki/page/BGG_XML_API

Open questions

• Whether approved tokens will gain expiry or refresh semantics later; today they do not expire, but the 2026 auth rollout is recent and policy may still move.
• Exact numeric rate limits per application are not published; "Usage" on the applications page is the only feedback loop. Stay at one request per ~2s until real limits are documented.
• Whether the "own collection while logged in" exception applies to token-less API calls with session cookies or only to the website export; test once the account has an approved application.