REST API Documentation // ANDROMEDA

◇ Basics

All endpoints live under a single base URL. Every path in this document is relative to it.

https://andromeda1957.com

Method — every endpoint is GET. There are no write operations.
Authentication — none. The API is open and read-only.
Responses — JSON (application/json), except the PGN endpoints which return text/plain; charset=utf-8.
Two surfaces — the master database (millions of historical games, 1840–2000) and the curated study-player archives.
Be considerate — there is no hard rate limit, but please keep request volume reasonable and set a descriptive User-Agent.

◇ Conventions & pagination

List endpoints are paginated. Pass page and page_size as query parameters. The default page size is 50 and the maximum is 100 (larger values are clamped down).

Paginated payloads share a common envelope around their results array:

{
  "count": 128,            // total matches found
  "page": 1,               // current page number
  "page_size": 50,         // items per page
  "page_count": 3,         // total number of pages
  "results": [ ... ],      // the page of items
  "next": "https://andromeda1957.com/api/v1/games/?q=...&page=2&page_size=50",
  "previous": null         // null on the first page
}

The master game search returns at most 500 matching games per query (reported as result_limit in the response); refine your query q to narrow large result sets.

◇ Errors

Errors use the appropriate HTTP status code and a consistent JSON body with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "missing_query",
    "message": "q is required."
  }
}

Status	Code	Meaning
400	`missing_query`	A required `q` parameter was empty.
400	`missing_player`	A required `player` parameter was empty.
400	`missing_opponent`	`head_to_head` mode needs an `opponent`.
400	`invalid_mode`	`mode` was not `summary` or `head_to_head`.
400	`invalid_pagination`	`page` or `page_size` was not a positive integer.
404	`not_found`	The requested game does not exist.
503	`stats_unavailable`	The master database is temporarily not connected.

◇ Master database 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
`mode`	no	`summary` (default) or `head_to_head`.
`player`	yes	Player name to resolve (e.g. `Capablanca`).
`opponent`	head-to-head	Second player; required when `mode=head_to_head`.

Example

curl "https://andromeda1957.com/api/v1/stats/?player=Capablanca"

Response

{
  "mode": "summary",
  "query": { "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 player value to disambiguate. 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://andromeda1957.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/",
        "html": "/game-search/a1b2c3d4/"
      }
    }
  ],
  "next": "https://andromeda1957.com/api/v1/games/?q=Fischer+Spassky+1972&page=2&page_size=10",
  "previous": null
}

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://andromeda1957.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://andromeda1957.com/api/v1/games/a1b2c3d4/pgn/" -o game.pgn

◇ Study-archive API

The study archive is Andromeda's hand-curated collection of complete game sets for individual study players. Games here are addressed by a readable player_slug/game_slug token.

GET /api/v1/public/players/

List the curated study players (those with at least one game).

Parameter	Required	Description
`q`	no	Filter players by name, slug, or source alias.

Example

curl "https://andromeda1957.com/api/v1/public/players/?q=tal"

Response

{
  "source": "public",
  "query": "tal",
  "count": 1,
  "results": [
    {
      "name": "Mikhail Tal",
      "slug": "mikhail-tal",
      "game_count": 2431,
      "criteria": "World Champion 1960-1961",
      "urls": {
        "api_games": "/api/v1/public/games/?archive_player=mikhail-tal",
        "html_games": "/players/mikhail-tal/games/",
        "html_about": "/players/mikhail-tal/about/"
      }
    }
  ]
}

GET /api/v1/public/games/

Search games across the study archive. Returns a paginated list of game summaries.

Parameter	Required	Description
`q`	no	Free-text query matched against players, event, site, date, ECO, and opening.
`archive_player`	no	Restrict to one archive by player slug, name, or alias.
`sort`	no	`asc` (default) or `desc` by game date.
`page`	no	Page number (default `1`).
`page_size`	no	Items per page (default 50, max 100).

Example

curl "https://andromeda1957.com/api/v1/public/games/?archive_player=mikhail-tal&q=B33&sort=desc"

Response

{
  "source": "public",
  "query": "B33",
  "archive_player": "mikhail-tal",
  "sort": "desc",
  "count": 14,
  "page": 1,
  "page_size": 50,
  "page_count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "token": "mikhail-tal/tal-vs-larsen-1965",
      "player": { "name": "Mikhail Tal", "slug": "mikhail-tal" },
      "white": "Tal, Mikhail",
      "black": "Larsen, Bent",
      "display_white": "Tal, Mikhail",
      "display_black": "Larsen, Bent",
      "result": "1-0",
      "result_key": "win",
      "event": "Candidates",
      "site": "Bled",
      "date": "1965.07.20",
      "played_on": "1965-07-20",
      "round": "5",
      "white_elo": null,
      "black_elo": null,
      "eco": "B33",
      "opening": "Sicilian, Sveshnikov",
      "move_count": 41,
      "source_game_id": "12345",
      "urls": {
        "api_detail": "/api/v1/public/games/mikhail-tal/tal-vs-larsen-1965/",
        "api_pgn": "/api/v1/public/games/mikhail-tal/tal-vs-larsen-1965/pgn/",
        "html": "/players/mikhail-tal/games/tal-vs-larsen-1965/",
        "pgn_download": "/players/mikhail-tal/games/tal-vs-larsen-1965/download/"
      }
    }
  ]
}

GET /api/v1/public/games/{player_slug}/{game_slug}/

Full detail for one archive game, including its full PGN in a "pgn" field.

Example

curl "https://andromeda1957.com/api/v1/public/games/mikhail-tal/tal-vs-larsen-1965/"

GET /api/v1/public/games/{player_slug}/{game_slug}/pgn/

The raw PGN for one archive game as text/plain.

Example

curl "https://andromeda1957.com/api/v1/public/games/mikhail-tal/tal-vs-larsen-1965/pgn/" -o tal.pgn

◇ Command-line client

If you'd rather not assemble URLs by hand, there is a small, dependency-free Python client, pull_api.py, that wraps every endpoint above. It needs only Python 3 (no third-party packages) and prints JSON — or PGN with --pgn — to stdout.

↧ Download pull_api.py or grab it from the shell:

curl -O https://andromeda1957.com/api/pull_api.py

Then run it

# Master database
python3 pull_api.py master stats --player Capablanca
python3 pull_api.py master games --players Fischer Spassky --year 1972
python3 pull_api.py master pgn a1b2c3d4 --output game.pgn

# Study archive
python3 pull_api.py public players --plain
python3 pull_api.py public games --archive-player mikhail-tal --eco B33 --all-pages
python3 pull_api.py public pgn mikhail-tal/tal-vs-larsen-1965

Add --base-url to point the client at a different host, --all-pages to follow pagination automatically, and --limit to cap the number of results.