Live

API-Referenz

Eine schlanke, schreibgeschützte REST-API für den gesamten mehrsprachigen Katalog — Spiele, Erweiterungen, Verlage, Autoren, Illustratoren, Themen und Mechaniken. Antworten sind JSON. Der Zugriff erfordert einen API-Schlüssel.

API-Schlüssel erhalten Interactive docs

Basis-URL

Alle Endpunkte sind versioniert und unter einer einzigen Basis-URL erreichbar. Die aktuelle Version ist v1.

https://boardgamebase.com/api/v1

Authentifizierung

Authentifiziere jede Anfrage mit deinem geheimen API-Schlüssel im Authorization-Header als Bearer-Token. Anfragen ohne gültigen Schlüssel werden mit 401 abgelehnt.

curl

curl https://boardgamebase.com/api/v1/games \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

API-Schlüssel sind kostenlos — melden Sie sich im Entwickler-Dashboard an, um einen zu erstellen.

Lokalisierung

Lokalisierte Felder (name, description) werden als Objekt mit einem Eintrag pro Sprache zurückgegeben. Ihr Client wählt die anzuzeigende Sprache.

GET /games/azul

{
  "id": "azul",
  "name": { "en": "Azul", "fr": "Azul" },
  "description": {
    "en": "Compose beautiful tiled walls…",
    "fr": "Composez de superbes murs de tuiles…"
  },
  "languages": ["en", "fr", "de", "es", "it"]
}

Supported: en, fr, de, es, it

Paginierung

Listen-Endpunkte verwenden Cursor-Pagination. Übergeben Sie limit (max. 50) und den cursor aus pagination.nextCursor der vorherigen Antwort; hasMore zeigt an, ob weitere Seiten folgen.

{
  "data": [ /* … */ ],
  "pagination": { "nextCursor": "azul", "hasMore": true }
}

Fehler

Fehler verwenden Standard-HTTP-Statuscodes und liefern einen RFC-9457-problem+json-Body mit einem maschinenlesbaren Code.

Parameter	Type	Description
200	OK	The request succeeded.
400	Bad Request	An invalid query parameter was supplied.
401	Unauthorized	Missing, invalid, or revoked API key.
404	Not Found	No resource matches the given slug.
429	Too Many Requests	Rate limit or monthly quota exceeded.

application/problem+json

{
  "type": "https://boardgamebase.com/docs/errors/not_found",
  "code": "not_found",
  "title": "Not found",
  "status": 404,
  "detail": "No game matches \"unknown-game\"."
}

Endpunkte

GET/v1/games

Spiele auflisten, suchen und filtern.

Parameter	Type	Description
q	string	Full-text, typo-tolerant search over the title.
year	integer	Exact year of publication.
language	string	ISO 639-1 code the game is published in.
mechanic	string	Mechanic slug.
category	string	Category (theme) slug.
publisher	string	Publisher slug.
players	integer	Games playable with exactly this player count.
cursor	string	Cursor from the previous response's pagination.nextCursor.
limit	integer	Items per page (default 20, max 50).

Request

curl "https://boardgamebase.com/api/v1/games?players=4&mechanic=deck-building&limit=20" \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "dominion",
      "name": { "en": "Dominion" },
      "yearPublished": 2008,
      "publisher": "Rio Grande Games",
      "players": { "min": 2, "max": 4 },
      "mechanics": ["deck-bag-and-pool-building"]
    }
  ],
  "pagination": { "nextCursor": "dominion", "hasMore": true }
}

GET/v1/games/{slug}

Ein einzelnes Spiel anhand seiner id abrufen, mit seinen Erweiterungen.

Request

curl "https://boardgamebase.com/api/v1/games/brass-birmingham" \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

Response

{ "data": {
    "id": "brass-birmingham",
    "name": { "en": "Brass: Birmingham", "fr": "Brass: Birmingham" },
    "description": {
      "en": "Build canals and rail across the industrial Midlands…",
      "fr": "Développez canaux et rails dans les Midlands industrielles…"
    },
    "yearPublished": 2018,
    "editions": 3,
    "players": { "min": 2, "max": 4 },
    "playtime": { "min": 60, "max": 120 },
    "minAge": 14,
    "languages": ["en", "fr", "de"],
    "publisher": "Roxley",
    "designers": ["Gavan Brown", "Matt Tolman", "Martin Wallace"],
    "illustrators": ["Lina Cossette", "David Forest"],
    "categories": ["economic"],
    "mechanics": ["network-building", "hand-management"],
    "expansions": []
  } }

GET/v1/games/{slug}/expansions

Every expansion of a single game.

GET/v1/expansions

List expansions across the catalog.

Parameter	Type	Description
baseGame	string	Base game slug.
year	integer	Exact year of publication.
language	string	ISO 639-1 code the expansion is published in.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [
    {
      "id": "brass-birmingham-blackpool",
      "name": { "en": "Brass: Birmingham – Blackpool" },
      "yearPublished": 2022,
      "languages": ["en"],
      "baseGame": "brass-birmingham"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

GET/v1/mechanics · /v1/categories

List all mechanics or categories with their localized labels.

Response

{
  "data": [
    { "id": "economic", "label": { "en": "Economic", "fr": "Économie" } },
    { "id": "abstract", "label": { "en": "Abstract", "fr": "Abstrait" } }
  ],
  "pagination": { "nextCursor": "abstract", "hasMore": true }
}

GET/v1/publishers

List publishers.

Parameter	Type	Description
q	string	Name search.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [ { "id": "roxley", "name": "Roxley" } ],
  "pagination": { "nextCursor": "roxley", "hasMore": true }
}

GET/v1/people

List designers and illustrators.

Parameter	Type	Description
q	string	Name search.
role	designer \| illustrator	Filter by credited role.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [ { "id": "martin-wallace", "name": "Martin Wallace" } ],
  "pagination": { "nextCursor": "martin-wallace", "hasMore": true }
}

Das game-Objekt

Jedes von der API zurückgegebene Spiel hat die folgende Struktur. Interne Bezeichner werden nie offengelegt.

Parameter	Type	Description
id	string	Stable, URL-friendly identifier (slug).
name	localized	Title as an object keyed by language code.
description	localized	Short description per language.
yearPublished	integer	Year of first publication.
editions	integer	Number of editions released.
players	{ min, max }	Supported player count.
playtime	{ min, max }	Typical play time in minutes.
minAge	integer	Recommended minimum age.
languages	string[]	ISO 639-1 codes the game is published in.
publisher	string \| null	Publishing company.
designers	string[]	Game designers.
illustrators	string[]	Box and component illustrators.
categories	string[]	Category (theme) slugs.
mechanics	string[]	Mechanic slugs.
expansions	object[]	Expansions for this game.

API-Schlüssel erhalten

Erstellen Sie ein kostenloses Entwicklerkonto, um einen Schlüssel zu generieren und loszulegen. Das kostenlose Kontingent ist großzügig — kostenpflichtige Pläne bieten höhere Limits.

Entwickler OpenAPI spec