Skip to content

About

Self-hosted, read-only HTTP API for chess opening statistics: query a position by moves or FEN, get next-move frequencies and W/D/L. Rust. Includes a curated 3.28M-game Masters OTB dataset (non-commercial) and an Elite Online collection.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

46 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Opening Explorer API

A self-hosted, read-only HTTP API for chess opening statistics. Give it a position (as a move sequence or a FEN) and it returns how many games reached it, the White / draw / Black results, and the moves that were played next, with their own results.

Opening Explorer API curates and deduplicates large game collections, stores them compactly, indexes every position, and serves the statistics from a small Rust service. It is written independently and shares no code with the AGPL-licensed Lichess opening explorer.

Availability. There is no hosted public instance. You run the service yourself. The Masters OTB R3 dataset is published as a GitHub release. Elite Online R1 is being prepared for a separate release from the pinned Lichess archive selection. Both releases contain an indexed dataset and a filtered PGN; their licenses and download status differ (Dataset releases).

Who it is for

  • Developers building an opening explorer or opening trainer into a chess app.
  • Analysts who want opening statistics in a pipeline (batch queries, CSV export).
  • Researchers who want curated, legal, deduplicated PGN to work with.

Collections

Two collections are kept strictly apart. Their ratings and statistics are never pooled.

masters-otb elite-online
Games 3,284,429 429,150
Source Lumbra's Gigabase OTB Complete (publisher-asserted over-the-board) Lichess rated archive
Rating scale Publisher-supplied Elo (FIDE-style) Lichess platform rating
Selection Standard legal chess, at least four plies, rating thresholds Both players 2200+, or one 2400+ and the other 2000+; no bullet; at least six plies
Indexed depth 40 plies 30 plies
Dataset license CC BY-NC 4.0 (publisher claim); non-commercial, attribution required CC0 1.0

Elite Online covers seven selected monthly archives from September 2015 through March 2017. It is historical data, not a feed of contemporary games. Its player ratings are Lichess Glicko-2 ratings and are not comparable to the Masters collection's FIDE-style Elo values.

Do not compare an OTB Elo with an online rating as if they were one scale. Details: API reference, interpreting statistics.

What the API provides

Endpoint Purpose
GET /v1/explorer/position Position statistics from moves= (SAN or UCI) or fen=: total games, W/D/L, next moves, each with W/D/L
GET /v1/collections Loaded collections and their dataset versions
GET /v1/collections/{collection}/games/{id} Canonical PGN of one stored game (enabled by default)
GET /health, GET /ready Liveness and readiness
POST /v1/admin/reload Token-protected hot reload of a newly published dataset

Full contract, errors, caching, and configuration: docs/API_REFERENCE.md.

Quick start

Build the CLI (opening-explorer), make a small sample dataset from the bundled synthetic fixture, serve it, and query it:

cargo build --locked --release --package opening-explorer-cli

./target/release/opening-explorer build \
  --input fixtures/stage_a_validation.pgn --collection elite-online \
  --output data/sample/elite-online
./target/release/opening-explorer build-index \
  --dataset data/sample/elite-online --collection elite-online

./target/release/opening-explorer serve \
  --elite-dataset data/sample/elite-online --host 127.0.0.1 --port 8080

In another terminal, ask for the position after 1.e4 e5 2.Nf3:

curl --get 'http://127.0.0.1:8080/v1/explorer/position' \
  --data-urlencode 'collection=elite-online' \
  --data-urlencode 'moves=e4,e5,Nf3'

The result lists total_games, white_wins, draws, black_wins, and a moves array with the same counts per candidate move. The sample is synthetic test data. Getting started walks through it step by step.

With Docker

cp .env.example .env          # point it at your dataset directory
docker compose up -d --build
curl http://127.0.0.1:8080/ready

See Deployment for read-only mounts, resource bounds, and operational settings.

Get the datasets

Both collection releases use two products, and the indexed and PGN products for one collection contain the same canonical games. Masters OTB R3 is published; Elite Online R1 is being prepared for a separate release.

Collection Indexed dataset Filtered PGN Coverage and license
Masters OTB R3 Published release, 3,284,429 games, CPI depth 40 Zstandard-compressed PGN in the same release CC BY-NC 4.0 publisher claim; non-commercial use with attribution. See the current policy.
Elite Online R1 Prepared for a separate release; publication is pending review and merge One complete canonical game per PGN record, Zstandard-compressed 429,150 games from selected Lichess rated archives in 2015–2017; CC0 1.0. Commercial redistribution is permitted under CC0.

The indexed package contains the immutable snapshot, position index, release metadata, and checksums. The filtered PGN preserves supported stored metadata and full legal mainlines. Masters R3's indexed package is split into two numbered assets; the Elite package is split only if it exceeds the per-asset limit. See Dataset releases for download links, checksum verification, reconstruction, installation, PGN extraction, and versioning. To reproduce Elite Online from the pinned sources, follow Corpus build.

Use cases

Worked examples are in docs/USE_CASES.md, with runnable code in examples/ (curl, dependency-free JavaScript, Python):

  1. Opening explorer in a chess app: query on every move and render next-move bars.
  2. Masters vs. Elite comparison: query both collections for one position and show them side by side, never merged.
  3. Next-move frequencies and W/D/L for a position.
  4. Analysis pipeline: batch positions through the API and export CSV.
  5. Curated PGN for research: use the filtered PGN download.

A minimal JavaScript client:

import { OpeningExplorer } from "./examples/js/opening-explorer.mjs";

const explorer = new OpeningExplorer("http://127.0.0.1:8080");
const result = await explorer.position({ collection: "elite-online", moves: ["e4", "e5", "Nf3"] });
console.log(result.total_games, result.moves[0]);

Documentation

Need Read
First run Getting started
Endpoints, errors, config API reference
Downloading and installing datasets Dataset releases
Running it in production Deployment
Building from source and rebuilding corpora Corpus build, Contributing
Data and licensing Licensing and attribution
Internals and formats Architecture, Data contracts
Benchmarks and research Benchmarks, research archive
Upgrading from the old codb names Migration

The complete index is docs/README.md.

Development

./scripts/validate.sh   # format, clippy, tests, evidence and documentation gates

Contribution rules are in CONTRIBUTING.md; agent workflow notes are in AGENTS.md.

Licenses

  • Software: MIT or Apache-2.0, at your option. These licenses do not apply to the datasets.
  • Masters OTB data: games from Lumbra's Gigabase, which the publisher offers under CC BY-NC 4.0. This project filtered, deduplicated, normalized, and indexed them; it claims no authorship of any game and is not endorsed by the publisher. Non-commercial use only, with attribution. Public, non-commercial deployment of the API (position statistics and single-game PGN retrieval) is supported under the maintainer's recorded decisions; commercial use is not covered. The terms for your application, the required acknowledgment, and the open questions are in docs/LICENSING.md.
  • Elite Online data: selected standard rated archives from Lichess, licensed under CC0 1.0 Universal. Opening Explorer filters, deduplicates, normalizes, and indexes these historical games; the data license is separate from the software license. See LICENSING.md for source periods and details.

Attribution text, changes made, and the open upstream-rights questions: docs/LICENSING.md.

About

Self-hosted, read-only HTTP API for chess opening statistics: query a position by moves or FEN, get next-move frequencies and W/D/L. Rust. Includes a curated 3.28M-game Masters OTB dataset (non-commercial) and an Elite Online collection.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages