HTTP API
Public JSON API (CORS enabled). Base URL is this site’s origin, e.g. https://your-domain/. Query params use date=YYYY-MM and type=standard|rapid|blitz where noted.
API call creator
Pick an endpoint, fill the fields, then Run. The URL updates automatically. Tables below still click-fill path + query.
1. Endpoint
2. Parameters
curl
Raw path & query (edit manually if you like)
Choose a recipe, adjust fields, Run.Quick: · · · ·
Lists & players
| Method | Path | Description |
|---|---|---|
| GET | /api/lists | Available list dates and types |
| GET | /api/lists/:date/:type | Full list; optional ?limit=, ?format=csv — type path manually (get date from /api/lists first) |
| GET | /api/top/:view | Top players: open, women, juniors, girls; ?date=&type=&limit= |
| GET | /api/country/:fed | Top by federation (e.g. USA); ?date=&type=&limit=. Each player includes represents_since (YYYY-MM start of current stint) and fed_always when another federation appears in data. |
| GET | /api/gains | Biggest rating gains vs previous list |
| GET | /api/losses | Biggest rating losses |
| GET | /api/titles/:title | Title holders (GM…WCM or ALL); ?date=&type=&limit=&fed=; first_title_list per player |
| GET | /api/player/:id | Player in a list (?date= default latest) — sample FIDE ID |
| GET | /api/player/:id/history | Rating history; ?type=&limit= |
| GET | /api/player/:id/current | Current standard/rapid/blitz snapshot |
| GET | /api/player/:id/profile | Profile + current ratings |
| GET | /api/search | ?q= — current + previous names (from history), FIDE ID; ?type= for rating column |
| GET | /api/federations | Federation codes / names |
| GET | /api/compare-countries | Compare federations on a list |
| GET | /api/lists/overview | List overview payload for the in-app lists UI |
| GET | /api/list-changes/new-titles | New titles vs previous list; ?list=YYYY-MM (default latest) |
| GET | /api/list-changes/fed-changes | Federation changes; ?list=YYYY-MM |
| GET | /api/list-changes/gender-changes | Gender changes; ?list=YYYY-MM&type=; optional name_changed=1 |
| GET | /api/titles-past/:title | Past title holders; ?type=&fed= (ALL, GM…WCM) |
| GET | /api/playerprofile/:fideId | Widget-oriented profile JSON; optional include_history=true&history_limit= (max 5000) |
Tools player info
Matches the Tools dropdown: each mode is available with ?mode=. Batch URL supports the same mode for every ID. Create PGN file is separate (POST to your app’s PGN route from the Tools page), not this JSON API.
?mode= (same as Tools)
mode | Tools label | Always | Extra by mode |
|---|---|---|---|
full | Full info | name | Latest row only, or add history[] (monthly lists for chosen type) with include_history=true |
standard | Standard rating | mode, name, fideid | standard_elo |
average | Average 12 mo | mode, name, fideid | average_rating_12m, months_used |
peak | Peak | mode, name, fideid | peak_rating, peak_numeric_date, peak_month_year |
peak12months | Peak 12 mo | mode, name, fideid | peak_rating, peak_numeric_date, peak_month_year, months_in_window |
Batch: each element of players[] matches the same field set as one single-player response for that mode.
Endpoints
| Method | Path | Notes |
|---|---|---|
| GET | /api/player/:id/info | ?mode=, ?type=standard|rapid|blitz. For mode=full, add include_history=true to append monthly history[]. |
| GET | /api/players/info | ?fideids= (max 80) + same mode for all. errors if not found or no history (for average/peak modes). |
| GET | /player/:id/info | Same as /api/player/:id/info (Tools page). |
Fields (one player object)
Each value is either a string or a number. Missing data uses the string "N/A" (same as Tools CSV).
| JSON field | Tools column | Description |
|---|---|---|
name | Name | Player name. |
standard_elo | Standard rating | Current classical rating as string, or N/A. |
rapid_elo | Rapid | Current rapid rating. |
blitz_elo | Blitz | Current blitz rating. |
world_rank_active_players | World rank (active) | World rank on the latest standard list (active players), or N/A. |
world_rank_rapid_active_players | — | World rank on latest rapid list (API only; same idea as standard). |
world_rank_blitz_active_players | — | World rank on latest blitz list. |
federation | Federation | Three-letter federation code. |
birth_year | Birth year | Four-digit year when available. |
sex | Sex | M / F or N/A. |
title | Title | FIDE + women’s title combined (e.g. GM, IM WGM). |
fideid | FIDE ID | Present when resolved; matches Tools row ID for numeric lookups. |
Optional history[] (full mode only)
Default is current list only (no big array). Set include_history=true when you want every month’s rating for the chosen type in one response.
| Field | Description |
|---|---|
history | Only if include_history=true and mode=full. One entry per list month (same order as /api/player/:id/history?type=). |
history[].standard | Rating that month (string; name kept for Tools CSV). |
history[].numeric_date | YYYYMM for that list. |
Stats
Paths under /api/stats/…. Most chart/table stats accept ?type=standard|rapid|blitz and inactive=1 where the server aggregates open lists — exceptions called out below. Responses are often cached in api_cache after first compute.
| Path | Notes |
|---|---|
/api/stats/adult-improvers | ?age=30|40|50|60&max_rating=1800–2600&country=XYZ&limit= (optional cap) |
/api/stats/age-rating-records | Standard only (type ignored). ?age=5–100&women=1&limit=≤200&inactive=1 |
/api/stats/avg-age | ?top=10|100&women=1&inactive=1 |
/api/stats/avg-games | ?top=10|100&women=1&inactive=1 |
/api/stats/avg-rating | ?top=10|100&women=1&inactive=1 |
/api/stats/birth-year-cohort | Standard only (type ignored). ?year= calendar birth year; cohort=overall|u20|u16|u14|u12; limit=10|100; women=1 |
/api/stats/birthdays-on-day | ?date=YYYY-MM-DD (year ignored) or ?month=&day= |
/api/stats/country-in-top | ?top=10|100&women=1&fed=; inactive=1 |
/api/stats/country-in-top-players | ?top=&women=1&fed= (no inactive on this route) |
/api/stats/fold-from-list-stats | Reads bundled fold_from_list_stats JSON from disk (404 if not generated) |
/api/stats/gender-changes | All-time list; optional name_changed=1 |
/api/stats/generational-success | ?top=10|100&women=1 |
/api/stats/milestone-crossings | ?metric=rating|world_rank|women_rank&threshold=&women=1&title=GM&inactive=1 |
/api/stats/most-games-year | Standard only. ?mode=year|all|period&year= or from=&to= (YYYY-MM), title=, min_rating=, limit= (empty = all rows up to 200) |
/api/stats/number-ones | ?women=1&inactive=1 |
/api/stats/player-count | ?activity=active|inactive|all&fed= (uses activity, not global inactive) |
/api/stats/rating-decline | ?min_peak=&women=1 |
/api/stats/rating-distribution | Standard only. ?year=; inactive=1 |
/api/stats/rating-threshold | ?min_rating=&title=GM|…|WCM&inactive=1 |
/api/stats/rating-type-presence | No type (all list types). inactive=1 |
/api/stats/revoked-titles | ?title=ALL|GM|… |
/api/stats/title-age-stats | ?title=&type= |
/api/stats/title-counts-over-time | Standard lists only (path always uses standard title data). inactive=1 |
/api/stats/title-yearly | ?title= (no rating type) |
/api/stats/top10-ever | Full open / women arrays (everyone with a career month in world top 10). inactive=1 |
/api/stats/women-percentage | ?pool=all|gm|im|…|1000&cohort=all|women|men&inactive=1 |
/api/stats/women-percentage-by-age | ?pool=&cohort=&inactive=1 |
/api/stats/women-percentage-by-rating-band | ?pool=&cohort=&inactive=1 |
/api/stats/women-percentage-age-rating | Intersection band; age_band + rating_band required (fixed vocabulary — see app UI) |
CSV helpers
| Path | Description |
|---|---|
/api/csv/lists | List export params |
/api/csv/player | Player CSV |
/api/csv/search | Search CSV |
Other
GET /api/health— health checkGET /api/warm-cache— cache warmup (ops; supports streaming and query flags — see server)GET /api/title-counts— per-list title counts for UI (?list=&type=&inactive=&fed=)