Master database | Classic Chess API

The master database holds millions of historical games (roughly 1840–2000). Use it to look up player statistics, search games, and pull individual game details or raw PGN. Games are addressed by an opaque token returned in every search result.

GET /api/v1/stats/

Player summary statistics, or a head-to-head record between two players.

Parameter	Required	Description
`q`	yes	Canonical stats query. Use one player name for a summary, or two names for head-to-head (e.g. `Tal Smyslov`).
`mode`	legacy	`summary` (default) or `head_to_head` when using legacy params.
`player`	legacy	Legacy player name to resolve (e.g. `Capablanca`).
`opponent`	legacy head-to-head	Legacy second player; required when `mode=head_to_head`.

Example

curl "https://classicchess.com/api/v1/stats/?q=Capablanca"

Response

{
  "mode": "summary",
  "query": { "q": "Capablanca", "player": "Capablanca", "opponent": "" },
  "player": {
    "query": "Capablanca",
    "selected": {
      "name": "Capablanca, Jose Raul",
      "search_name": "capablanca jose raul",
      "aliases": ["Capablanca", "Capablanca, J.R."],
      "game_count": 1234,
      "max_elo": 2725
    },
    "candidates": [ { "name": "...", "game_count": 1234, "max_elo": 2725 } ]
  },
  "opponent": null,
  "result": {
    "total": 1234, "wins": 600, "losses": 134, "draws": 500,
    "as_white": 620, "as_black": 614
  },
  "opening_insights": { "...": "per-opening breakdown, or null" }
}

When a name is ambiguous, selected may be null and candidates lists the possible matches — refine the q value to disambiguate. Legacy mode, player, and opponent params remain accepted. For head_to_head, opponent mirrors the player block and result is the record from player's point of view.

GET /api/v1/games/

Search the master database for games. Returns a paginated list of game summaries.

Parameter	Required	Description
`q`	yes	Free-text query. Combine player names, an ECO code, and/or a year (e.g. `Fischer Spassky 1972` or `Kasparov B33`).
`page`	no	Page number (default `1`).
`page_size`	no	Items per page (default 50, max 100).

Example

curl "https://classicchess.com/api/v1/games/?q=Fischer+Spassky+1972&page_size=10"

Response

{
  "count": 21,
  "page": 1,
  "page_size": 10,
  "page_count": 3,
  "result_limit": 500,
  "query": "Fischer Spassky 1972",
  "results": [
    {
      "token": "a1b2c3d4",
      "white": "Spassky, Boris V",
      "black": "Fischer, Robert James",
      "display_white": "Spassky, Boris V",
      "display_black": "Fischer, Robert James",
      "result": "1/2-1/2",
      "event": "World Championship",
      "site": "Reykjavik",
      "date": "1972.07.11",
      "played_on": "1972-07-11",
      "year": 1972,
      "round": "1",
      "white_elo": 2660,
      "black_elo": 2785,
      "eco": "E56",
      "opening": "Nimzo-Indian Defence",
      "ply_count": 112,
      "move_count": 56,
      "source_count": 3,
      "urls": {
        "api_detail": "/api/v1/games/a1b2c3d4/",
        "api_pgn": "/api/v1/games/a1b2c3d4/pgn/",
        "gif": "/api/v1/games/a1b2c3d4/gif/",
        "html": "/game-search/a1b2c3d4/"
      }
    }
  ],
  "next": "https://classicchess.com/api/v1/games/?q=Fischer+Spassky+1972&page=2&page_size=10",
  "previous": null
}

GET/POST /api/v1/games/export/

Export up to 300 MasterDB games per request as a PGN bundle or newline-delimited JSON. Query exports stop at the first 300 matches.

Parameter	Required	Description
`q`	no	Export the current search result set (up to the API result limit).
`tokens`	no	Comma-separated game tokens, max 300. POST may send the same list as plain text, up to 64 KiB.
`format`	no	`pgn` (default) or `ndjson`.
`pgnInJson`	no	Include PGN in NDJSON rows (default true).

Example

curl "https://classicchess.com/api/v1/games/export/?q=Fischer+Spassky+1972" -o games.pgn
curl "https://classicchess.com/api/v1/games/export/?q=Fischer+Spassky+1972&format=ndjson"

GET /api/v1/games/{token}/

Full detail for one master game, including its full PGN. The token comes from a search result.

Example

curl "https://classicchess.com/api/v1/games/a1b2c3d4/"

The body is the same object shown in search results, plus a "pgn" field containing the full game text.

GET /api/v1/games/{token}/pgn/

The raw PGN for one master game as text/plain, ready to save or import elsewhere.

Example

curl "https://classicchess.com/api/v1/games/a1b2c3d4/pgn/" -o game.pgn

GET /api/v1/games/{token}/gif/

Registered-account animated GIF export for one master game. Add orientation=black to flip the board, or format=mp4 for an MP4 video.

Example

curl -H "Authorization: Bearer $TOKEN" "https://classicchess.com/api/v1/games/a1b2c3d4/gif/" -o game.gif