Online

Riferimento API

Un'API REST pulita e di sola lettura su tutto il catalogo multilingue: giochi, espansioni, editori, autori, illustratori, temi e meccaniche. Le risposte sono in JSON. L'accesso richiede una chiave API.

Ottieni una chiave API Interactive docs

URL di base

Tutti gli endpoint sono versionati e raggruppati sotto un unico URL di base. La versione attuale è v1.

https://boardgamebase.com/api/v1

Autenticazione

Autentica ogni richiesta con la tua chiave API segreta nell'intestazione Authorization come token Bearer. Le richieste senza una chiave valida vengono rifiutate con un 401.

curl

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

Le chiavi API sono gratuite: accedi alla dashboard sviluppatore per generarne una.

Localizzazione

I campi localizzati (name, description) sono restituiti come oggetto con una voce per lingua. Il tuo client sceglie quale lingua mostrare.

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

Paginazione

Gli endpoint di elenco usano la paginazione a cursore. Passa limit (max 50) e il cursor dal pagination.nextCursor della risposta precedente; hasMore indica se restano altre pagine.

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

Errori

Gli errori usano codici di stato HTTP standard e restituiscono un corpo problem+json (RFC 9457) con un codice leggibile dalla macchina.

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

Endpoint

GET/v1/games

Elencare, cercare e filtrare i giochi.

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}

Recuperare un singolo gioco tramite il suo id, con le sue espansioni.

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'oggetto game

Ogni gioco restituito dall'API ha la struttura seguente. Gli identificatori interni non sono mai esposti.

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.

Ottieni una chiave API

Crea un account sviluppatore gratuito per generare una chiave e iniziare. Il piano gratuito è generoso — i piani a pagamento sbloccano limiti più alti.

Sviluppatori OpenAPI spec