Classic Chess Python SDK

Use Python to read chess games, player biographies, notable games, tournament archives and annotated books from Classic Chess. The SDK also searches the larger MasterDB game database, retrieves opening statistics, exports games, and calls account and application APIs.

Public reads need no account or API key. The SDK uses the Python standard library and is MIT licensed; see LICENSE.

Install and run your first example

Install Python 3.10 or newer. In a terminal, create an isolated Python environment and install from PyPI:

python3 -m venv classicchess-env
source classicchess-env/bin/activate
python3 -m pip install classicchess-sdk
classicchess-api public players --names

On Windows PowerShell, use py instead of python3 and activate with classicchess-env\Scripts\Activate.ps1 instead of the source command. The last command prints the names of all curated players. To install from the public source repository instead, install Git and use python3 -m pip install git+https://github.com/Andromeda1957/classicchess-api-python.git.

To use it in a Python program, create example.py with this complete example:

from classicchess_api import ClassicChessClient

api = ClassicChessClient()
print(api.player_names()[:10])

Run python3 example.py in the same activated environment. You should see up to ten player names. The PyPI distribution is classicchess-sdk; the import is classicchess_api and the command-line executable is classicchess-api. python3 -m classicchess_api runs the same command-line tool.

If you installed the previous classicchess-api distribution, run python3 -m pip uninstall classicchess-api before installing classicchess-sdk in that environment. Both distributions provide the same import and command, so install only one. Existing Python programs and CLI commands still work.

Read a player archive

Player slugs are identifiers returned by the API. Use them as returned rather than guessing a slug from a display name. This complete example discovers a player and prints the first ten games in their archive:

from classicchess_api import ClassicChessClient

api = ClassicChessClient()
players = api.public_players()["results"]
if players:
    player = players[0]
    print(player["name"])
    biography = api.public_player_bio(player["slug"])["bio"]
    print(biography["lede"] if biography else "Biography unavailable")
    for game in api.iterate_public_games(archive_player=player["slug"], limit=10):
        print(game["token"], game["white"], game["black"])

Catalogs return complete lists. Game searches return one page by default. The iterate_* methods fetch pages as you consume them; breaking the loop or setting limit stops without fetching an extra page. The all_pages=True option on game-list methods collects pages into one dictionary instead. Missing biographies are None, and notable lists can be empty.

Available operations

Public game filters include query, archive_player, archive_event, search_mode, since, until, sort, page and page_size. search_mode chooses which fields query searches: players (players, event, site and date), openings (opening name and ECO) or all (the default). Each export is capped at 300 games. For larger archives, iterate games and export batches of up to 300 returned tokens. NDJSON means one JSON object per line; pgn_in_json=False omits the PGN field from that format. PGN is the standard text format for chess games.

Account and application requests

Public archive reads use ClassicChessClient. For private account or device operations use ApplicationClient and pass a token explicitly for each request. Create a personal API token in your signed-in Classic Chess profile settings with the scopes required by the account API reference. Set the CLASSICCHESS_API_TOKEN environment variable to that token before running this read-only account example:

import os
from classicchess_api import ApplicationClient

api = ApplicationClient()
response = api.account_me(os.environ["CLASSICCHESS_API_TOKEN"])
print(response.status, response.data)

response.ok indicates HTTP success. HTTP JSON errors preserve their status, data and retry_after; network failures and invalid responses raise ApiError. Application requests accept JSON text or bytes, including binary notebook uploads. Scanner uploads accept JPEG bytes up to 850,000 bytes. Account tokens and mobile or Desktop device sessions have different scopes; use the credential required by the endpoint. Do not embed tokens in source files.

GIF, chapter PGN and Notebook file methods return an ApplicationDownload with ok, status, content (the file bytes when ok), content_type, filename, retry_after and error (the JSON error reply otherwise). GIF exports need a registered account, so any personal token or device session works, and they share the site limit on GIF exports: honor retry_after after a 429. This saves a GIF of a public archive game:

import os
from classicchess_api import ApplicationClient

gif = ApplicationClient().public_game_gif("tal-vs-larsen-1965", os.environ["CLASSICCHESS_API_TOKEN"])
if gif.ok:
    with open(gif.filename or "game.gif", "wb") as handle:
        handle.write(gif.content)
else:
    print(gif.status, gif.error)

Play the Gym's bots

Any account can play the Gym's bots; the moves are computed on the server. Personal tokens need gym:read to read games and gym:play to start and play them. Send the ply from the latest game state with each move: a stale ply returns 409 and plays nothing, so a repeated request is safe. The bot engine plays one move at a time. While it is busy, account_gym_bot_move returns 429 with capacity_exhausted: wait retry_after seconds and ask again with the same ply. Each account may use 30 minutes of engine time in each hour; once it is spent the answer is 429 engine_budget with retry_after set to the seconds until that hour ends. An account starts at most 30 games an hour.

import os
import time
from classicchess_api import ApplicationClient

token = os.environ["CLASSICCHESS_API_TOKEN"]  # a token with gym:read and gym:play
api = ApplicationClient()
created = api.account_gym_new_game("morphy", token, color="white", time="5+0")
if not created.ok:
    raise SystemExit(f"{created.status} {created.data}")
game = api.account_gym_move(created.data["id"], "e2e4", created.data["ply"], token).data
reply = api.account_gym_bot_move(game["id"], game["ply"], token)
while reply.status == 429 and reply.data["error"]["code"] == "capacity_exhausted":
    time.sleep(int(reply.retry_after or 1))
    reply = api.account_gym_bot_move(game["id"], game["ply"], token)
print(reply.status, reply.data.get("sans"), reply.data.get("clock"))

Play puzzles

Puzzles come from master games and are for signed-in accounts only. Personal tokens need puzzles:read to read puzzles, figures and history and puzzles:write to save a result or reset; cookie sessions are never enough. Each account has its own rotation: a puzzle solved on the first try leaves it until reset, and a missed one stays. A puzzle carries the game so far (start_fen and lead), the position (fen) and solution.moves: the accepted solver moves at each point are the entries whose after equals the moves played so far. Save each play once, missed at the first wrong move or when the solution is shown and solved for a clean finish. A 404 rotation_empty reply means every puzzle is solved; reset to play them again.

This plays one puzzle in the terminal and saves how it went:

import os
from classicchess_api import ApplicationClient

token = os.environ["CLASSICCHESS_API_TOKEN"]  # a token with puzzles:read and puzzles:write
api = ApplicationClient()
puzzle = api.account_puzzle_next(token)
if not puzzle.ok:
    raise SystemExit(f"{puzzle.status} {puzzle.data}")
print(puzzle.data["prompt"], puzzle.data["fen"])
played, result = [], "solved"
while True:
    accepted = {m["move"]: m["reply"] for m in puzzle.data["solution"]["moves"] if m["after"] == played}
    answer = input("Your move in UCI, such as e2e4: ").strip()
    if answer not in accepted:
        result = "missed"
        break
    played.append(answer)
    if accepted[answer] is None:
        break
    print("Reply:", accepted[answer])
    played.append(accepted[answer])
saved = api.account_puzzle_result(puzzle.data["id"], result, token)
print(saved.data["result"], saved.data["summary"])

The CLI reads CLASSICCHESS_API_TOKEN for account commands. Existing installations can continue using their previous token environment variable as a fallback. The original account helpers on ClassicChessClient remain available and raise ApiError for unsuccessful HTTP responses.

Timeouts, pagination and failures

Configure ClassicChessClient(timeout=30, max_response_bytes=32 * 1024 * 1024) or ApplicationClient with the same options. Public reads return dictionaries or text; ApiError exposes status_code, code and retry_after when available. Pagination rejects repeated pages and links outside the original API collection. The application transport sends no cookies, follows no redirects, and accepts bearers only on private API paths over HTTPS or loopback development. There are no automatic retries. Respect Retry-After and avoid blindly retrying writes.

Optional standalone command-line script

If you only want command-line commands without installing the Python package, GitHub also provides pull_api.py. Save that file and run python3 pull_api.py public players --names. It is the dependency-free CLI variant; the importable SDK and application transport are installed by the steps above. The Classic Chess website no longer serves a script download URI.

Build and test this repository

These contributor commands start from a fresh clone:

git clone https://github.com/Andromeda1957/classicchess-api-python.git
cd classicchess-api-python
python3 -m venv .venv
source .venv/bin/activate
python3 -m unittest discover -s classicchess_api/tests -t .
python3 -m pip install .

The same API capabilities are available in the TypeScript SDK and Kotlin SDK. See the API reference for response fields, endpoint permissions, rate limits and data attribution. The MIT license covers the SDK code; linked chess resources retain their own stated reuse terms. Issues and pull requests are welcome; see CONTRIBUTING.md.