BoardGameGeek APIboardgamegeek.com ↗
Search BoardGameGeek's tabletop game database and retrieve ratings, complexity scores, player counts, mechanics, designers, and full game metadata via two clean endpoints.
What is the BoardGameGeek API?
The BoardGameGeek API gives you two endpoints to search and inspect tabletop game data from BGG's database of hundreds of thousands of titles. search_games runs full-text queries against primary and alternate game names, returning BGG identifiers, publication years, and game types. get_game_details resolves any numeric game ID into over 15 structured fields including Bayesian ratings, complexity score, player-count range, mechanics, categories, designers, and ownership counts.
curl -X GET 'https://api.parse.bot/scraper/5d314781-0ef6-40ca-a94c-30794fd21bd2/search_games?type=boardgame&limit=10&query=Catan' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace boardgamegeek-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: BoardGameGeek SDK — search games, drill into details, filter by type."""
from parse_apis.boardgamegeek_com_api import BoardGameGeek, GameType, GameNotFound
client = BoardGameGeek()
# Search for base games matching a query; limit caps total items fetched.
for game in client.game_summaries.search(query="Gloomhaven", type=GameType.BOARDGAME, limit=5):
print(game.name, game.year_published)
# Drill-down: take one result and fetch full details via the typed nav op.
hit = client.game_summaries.search(query="Catan", limit=1).first()
if hit:
detail = hit.details()
print(detail.name, detail.average_rating, detail.complexity)
print("Designers:", detail.designers)
print("Mechanics:", detail.mechanics[:3])
for rank in detail.ranks:
print(f" {rank.name}: #{rank.rank}")
# Search expansions specifically.
for exp in client.game_summaries.search(query="Catan", type=GameType.EXPANSION, limit=3):
print(exp.name, exp.type)
# Typed error handling: catch a not-found when fetching details for a bad ID.
try:
bad = client.game_summaries.search(query="zzzznonexistent", limit=1).first()
if bad:
bad.details()
except GameNotFound as exc:
print(f"Game not found: {exc.game_id}")
print("exercised: game_summaries.search / details / GameType enum / GameNotFound error")
Full-text search over BoardGameGeek's database of tabletop games. Results include the BGG identifier, title, year published, and game type (base game or expansion). Results are ordered by relevance. The search covers primary and alternate game names.
| Param | Type | Description |
|---|---|---|
| type | string | Filter results by game type. |
| limit | integer | Maximum number of results to return (up to 100). |
| queryrequired | string | Search term to match against game titles. |
{
"type": "object",
"fields": {
"type": "string",
"query": "string",
"results": "array of game summaries with id, name, type, year_published, href",
"total_results": "integer"
},
"sample": {
"data": {
"type": "boardgame",
"query": "Catan",
"results": [
{
"id": "13",
"href": "/boardgame/13/catan",
"name": "Catan",
"type": "boardgame",
"year_published": 1995
}
],
"total_results": 10
},
"status": "success"
}
}About the BoardGameGeek API
Search the BGG Game Database
The search_games endpoint accepts a required query string and runs it against BoardGameGeek's full title index, covering both primary and alternate game names. Results include each game's numeric BGG id, name, year_published, type (base game or expansion), and a direct href to the BGG page. Use the optional type parameter to restrict results to base games or expansions, and limit (up to 100) to control result set size. The total_results field tells you how many matches exist in total.
Retrieve Full Game Details
get_game_details takes a single game_id — the numeric BGG identifier you can grab from search results — and returns a detailed record. Structured fields include min_age, complexity (BGG's 1–5 Weight scale derived from community votes), designers, publishers, categories, mechanics, num_owned, and ranks (an array of rank objects covering overall board game rank and subdomain ranks like strategy or family games). Ratings come back as both a plain average and a Bayesian-adjusted figure, which BGG uses for its ranked lists.
Notes on Game Identifiers
BGG game IDs are stable numeric strings. Well-known examples: 13 for Catan, 174430 for Gloomhaven, 161936 for Pandemic Legacy Season 1. If you already know a game's BGG ID you can call get_game_details directly without going through search. Expansion records return type: boardgameexpansion and carry the same detail fields as base games.
The BoardGameGeek API is a managed, monitored endpoint for boardgamegeek.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when boardgamegeek.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official boardgamegeek.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a game recommender that filters by
complexityscore andmechanicsto match player skill level. - Track BGG rank changes over time for a watchlist of games using the
ranksarray fromget_game_details. - Populate a board game collection app with cover metadata, player counts, and playing time pulled by BGG ID.
- Compare community ownership (
num_owned) across a set of games to gauge market penetration. - Identify all expansions for a title by searching its name with
typefiltered toboardgameexpansion. - Enrich a retail product catalog with BGG ratings, designer credits, and category tags.
- Generate a curated list of top family or strategy games by combining
search_gamesqueries with subdomain rank data.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does BoardGameGeek have an official developer API?+
What does the `ranks` field in `get_game_details` contain?+
name (e.g. 'boardgame', 'strategygames', 'familygames') and a numeric rank. A game ranked in multiple BGG subdomains will have multiple entries. Games that haven't received enough ratings may return unranked for some or all subdomain ranks.Does the API return user reviews or forum posts for a game?+
get_game_details. User-written reviews and forum thread data are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting BGG's reviews or comment data.