En ligne

Référence de l'API

Une API REST claire et en lecture seule sur tout le catalogue multilingue — jeux, extensions, éditeurs, auteurs, illustrateurs, thèmes et mécaniques. Les réponses sont en JSON. L'accès nécessite une clé API.

Obtenez une clé API Interactive docs

URL de base

Tous les points d'accès sont versionnés et regroupés sous une seule URL de base. La version actuelle est v1.

https://boardgamebase.com/api/v1

Authentification

Authentifiez chaque requête avec votre clé API secrète dans l'en-tête Authorization, en jeton Bearer. Les requêtes sans clé valide sont rejetées avec un code 401.

curl

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

Les clés API sont gratuites — connectez-vous au tableau de bord développeur pour en générer une.

Localisation

Les champs localisés (name, description) sont renvoyés sous forme d'objet avec une entrée par langue. Votre client choisit la langue à afficher.

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

Pagination

Les endpoints de liste utilisent une pagination par curseur. Passez limit (max 50) et le cursor issu du pagination.nextCursor de la réponse précédente ; hasMore indique s'il reste des pages.

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

Erreurs

Les erreurs utilisent les codes de statut HTTP standard et renvoient un corps problem+json (RFC 9457) avec un code lisible par machine.

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\"."
}

Points d'accès

GET/v1/games

Lister, rechercher et filtrer les jeux.

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}

Récupérer un jeu par son id, avec ses extensions.

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 }
}

L'objet game

Chaque jeu renvoyé par l'API a la structure suivante. Les identifiants internes ne sont jamais exposés.

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.

Obtenez une clé API

Créez un compte développeur gratuit pour générer une clé et commencer. L'offre gratuite est généreuse — les offres payantes débloquent des limites plus élevées.

Développeurs OpenAPI spec