Chess-Results APIchess-results.com ↗
Access chess tournament listings, round schedules, pairings, and upcoming games for any FIDE federation via the chess-results.com API.
What is the Chess-Results API?
The chess-results.com API exposes 4 endpoints covering tournament listings, round schedules, pairings, and a 14-day lookahead of upcoming games across any FIDE federation. The get_round_pairings endpoint returns board-by-board matchups including player names, ratings, current points, and results, while list_tournaments lets you browse all registered events for a given federation code and filter by status.
curl -X GET 'https://api.parse.bot/scraper/6cfbc235-7768-4f73-ad21-6f656ef67685/list_tournaments?status=playing&federation=ISR' \ -H 'X-API-Key: $PARSE_API_KEY'
List tournaments registered under a chess federation with their current status. Tournaments are sorted by most recent activity. Each tournament includes a unique ID that can be used with other endpoints to fetch schedule and pairing details.
| Param | Type | Description |
|---|---|---|
| status | string | Filter by tournament status. Omitting returns all tournaments. |
| federation | string | Three-letter FIDE federation code (e.g. ISR, USA, GER, RUS, FRA). |
{
"type": "object",
"fields": {
"total": "integer",
"federation": "string",
"tournaments": "array of tournament objects"
},
"sample": {
"data": {
"total": 27,
"federation": "ISR",
"tournaments": [
{
"url": "https://chess-results.com/tnr1443093.aspx?lan=1",
"name": "PT Classic JUN-JUL 2026",
"number": 1,
"status": "playing",
"last_update": "St1 Hours 41 Min.",
"tournament_id": "1443093"
}
]
},
"status": "success"
}
}About the Chess-Results API
Tournament Discovery
The list_tournaments endpoint accepts an optional three-letter FIDE federation code (e.g. ISR, USA, GER) and an optional status filter. It returns a tournaments array where each object carries a unique numeric tournament_id used by the other three endpoints, plus a total count and the federation code. Omitting both parameters returns all available tournaments sorted by most recent activity.
Schedules and Pairings
get_tournament_schedule takes a tournament_id and returns a rounds array with the date and time for each round, alongside tournament_name. Once you know which round you want, get_round_pairings accepts a tournament_id and a round number and returns a pairings array with board number, white and black player names, both players' ratings, their current point totals, and a result field that is null for games not yet played. total_boards gives the count of pairings in that round.
Upcoming Games Across a Federation
get_upcoming_games is an aggregate endpoint that scans active tournaments for a federation and collects all rounds falling within the next 14 days. The response includes a date_range object with ISO start and end dates, a games array, and total_tournaments_with_games. The optional max_tournaments parameter caps how many active tournaments are checked, which is useful for large federations. Rounds that have not yet been paired return an empty pairings array rather than an error.
Coverage Notes
All federation filtering uses standard three-letter FIDE federation codes. Tournament IDs are numeric strings assigned by chess-results.com and are stable across requests, making them safe to cache or store for polling round results over the course of a multi-round event.
The Chess-Results API is a managed, monitored endpoint for chess-results.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when chess-results.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official chess-results.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a federation dashboard showing all active tournaments and their current status for a given FIDE country code.
- Alert players when pairings for their round are published by polling
get_round_pairingsuntil the result field is non-null. - Populate a calendar widget with round dates and times from
get_tournament_schedulefor upcoming events. - Aggregate the next two weeks of games across a national federation using
get_upcoming_gamesand display them in a single feed. - Track a specific player's results round-by-round by scanning pairing objects for their name across multiple rounds.
- Monitor rating-weighted matchups by filtering pairings where both players' ratings exceed a threshold.
- Power a tournament bracket or standings page that updates automatically as
resultfields change from null to a score.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does chess-results.com offer an official developer API?+
What does `get_round_pairings` return for a round that hasn't been played yet?+
result field on each pairing object is null. If a round within get_upcoming_games has not yet been paired at all, the pairings array for that round will be empty rather than returning an error.Does the API return individual player statistics or historical rating data?+
Can I filter tournaments by time control, event type, or arbiter?+
list_tournaments endpoint currently filters by status and federation only. Fields like time control or event category are not exposed as filter parameters. You can fork the API on Parse and revise it to add finer-grained filtering if those fields are available on the source pages.How do I limit the number of tournaments checked when using `get_upcoming_games` for a large federation?+
max_tournaments parameter. This caps how many active tournaments are queried when building the upcoming-games response, which keeps response times predictable for federations like USA or RUS that may have many concurrent events.