En vivo

Referencia de la API

Una API REST limpia y de solo lectura sobre todo el catálogo multilingüe: juegos, expansiones, editoriales, autores, ilustradores, temas y mecánicas. Las respuestas son JSON. El acceso requiere una clave de API.

Consigue una clave de API Interactive docs

URL base

Todos los puntos de acceso están versionados y se agrupan bajo una única URL base. La versión actual es v1.

https://boardgamebase.com/api/v1

Autenticación

Autentica cada solicitud con tu clave de API secreta en la cabecera Authorization como token Bearer. Las solicitudes sin una clave válida se rechazan con un 401.

curl

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

Las claves de API son gratuitas: inicia sesión en el panel de desarrollador para generar una.

Localización

Los campos localizados (name, description) se devuelven como un objeto con una entrada por idioma. Tu cliente elige qué idioma mostrar.

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

Paginación

Los endpoints de lista usan paginación por cursor. Pasa limit (máx. 50) y el cursor del pagination.nextCursor de la respuesta anterior; hasMore indica si quedan más páginas.

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

Errores

Los errores usan códigos de estado HTTP estándar y devuelven un cuerpo problem+json (RFC 9457) con un código legible por máquina.

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

Puntos de acceso

GET/v1/games

Listar, buscar y filtrar juegos.

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}

Obtener un juego por su id, con sus expansiones.

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

El objeto game

Cada juego devuelto por la API tiene la siguiente estructura. Los identificadores internos nunca se exponen.

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.

Consigue una clave de API

Crea una cuenta de desarrollador gratuita para generar una clave y empezar. El plan gratuito es generoso; los planes de pago desbloquean límites más altos.

Desarrolladores OpenAPI spec