Chess APIapi.chess.com ↗
Retrieve top-ranked Chess.com players by category — blitz, rapid, bullet, and more. Access ratings, win/loss/draw counts, titles, and profile data for up to 50 players.
What is the Chess API?
The Chess.com Leaderboards API exposes 12 response fields per player — including rating, title, win/loss/draw counts, and country — through the get_leaderboard endpoint. Pass a category parameter to target game formats such as blitz, rapid, bullet, or daily chess, and use the top parameter to limit results to between 1 and 50 pre-ranked players. No sorting or post-processing is required; the server returns players in rank order.
curl -X GET 'https://api.parse.bot/scraper/5b5d974a-70f7-4ed0-b196-21f57600856d/get_leaderboard?top=5&category=daily' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace api-chess-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Chess.com Leaderboards SDK — bounded, re-runnable; every call capped."""
from parse_apis.api_chess_com_api import ChessCom, Category, InvalidCategory
client = ChessCom()
# Fetch top blitz players — limit= caps total items returned.
for player in client.leaderboards.get(category=Category.LIVE_BLITZ, limit=3):
print(player.username, player.rating, player.title)
# Drill-down: take the #1 rapid player with .first().
top_rapid = client.leaderboards.get(category=Category.LIVE_RAPID, limit=1).first()
if top_rapid:
print(top_rapid.name, top_rapid.country, top_rapid.win_count)
# Typed error: catch an invalid-category response.
try:
client.leaderboards.get(category=Category.LIVE_BULLET, limit=2).first()
except InvalidCategory as e:
print(f"bad category: {e.category}")
print("exercised: leaderboards.get")
Retrieve the top N players from a Chess.com leaderboard category. Each category contains up to 50 ranked players with their rating, title, win/loss/draw counts, and profile URL. Results are pre-ranked by the server; no client-side sorting is needed.
| Param | Type | Description |
|---|---|---|
| top | integer | Maximum number of players to return (1–50). |
| category | string | Leaderboard category to retrieve. |
{
"type": "object",
"fields": {
"players": "array of player objects with rank, username, rating, score, title, name, country, url, win_count, loss_count, draw_count, status",
"category": "string — the leaderboard category returned",
"total_in_category": "integer — total players available in this category (up to 50)"
},
"sample": {
"data": {
"players": [
{
"url": "https://www.chess.com/member/ManuDavid2910",
"name": "Manu David",
"rank": 1,
"score": 2966,
"title": "FM",
"rating": 2966,
"status": "premium",
"country": "IN",
"username": "ManuDavid2910",
"win_count": 289,
"draw_count": 16,
"loss_count": 37
},
{
"url": "https://www.chess.com/member/GutovAndrey",
"name": "Andrey Gutov",
"rank": 2,
"score": 2938,
"title": "GM",
"rating": 2938,
"status": "premium",
"country": "US",
"username": "GutovAndrey",
"win_count": 153,
"draw_count": 3,
"loss_count": 1
}
],
"category": "live_rapid",
"total_in_category": 50
},
"status": "success"
}
}About the Chess API
What get_leaderboard Returns
The get_leaderboard endpoint returns an array of player objects, each containing rank, username, rating, score, title (e.g. GM, IM, FM), name, country, url, win_count, loss_count, draw_count, and status. The response also includes a top-level category string confirming which leaderboard was queried and a total_in_category integer indicating how many players are available (capped at 50).
Input Parameters
Two optional parameters control the response. category selects the game format — supported values include blitz, rapid, bullet, daily, and variants like chess960. top accepts an integer from 1 to 50 and trims the result to only the requested number of leading players. If neither parameter is provided, the endpoint returns the default leaderboard in full.
Data Coverage and Freshness
Leaderboard data reflects Chess.com's public rankings, which are updated periodically by Chess.com's own systems. Ratings shown are the players' current published ratings for the selected time control. Fields like title and country are pulled from each player's public profile and may be empty if the player has not set them. The url field links directly to the player's Chess.com profile page.
The Chess API is a managed, monitored endpoint for api.chess.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when api.chess.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 api.chess.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 live ratings tracker that monitors rank and rating changes for top blitz or rapid players over time.
- Populate a chess tournament seeding tool using current
ratingandwin_countdata from a specific category. - Display a country-filtered leaderboard by reading the
countryfield on each returned player object. - Create an analytics dashboard comparing win/loss/draw ratios across the top 50 players in a given format.
- Generate weekly reports on which titled players (GM, IM, FM) appear in a leaderboard category using the
titlefield. - Feed a sports data aggregator with current chess standings alongside other competitive game rankings.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Chess.com have an official public developer API?+
What does the `category` parameter accept, and how does it affect results?+
category parameter selects the game format for the leaderboard. Supported values include blitz, rapid, bullet, daily, chess960daily, live960, and others published by Chess.com. Each category returns an independent ranked list; ratings and records shown are specific to that time control or variant.Does the API return historical leaderboard snapshots or trend data?+
get_leaderboard endpoint returns the current standings only — a single snapshot of up to 50 players at the time of the request. Historical snapshots and rating trend data are not part of this API. You can fork it on Parse and revise it to add a scheduled data-collection endpoint that stores periodic snapshots for trend analysis.Can I retrieve data for players ranked below the top 50?+
Are game-specific stats like accuracy or opening repertoire included in player objects?+
get_leaderboard cover rating, win_count, loss_count, draw_count, title, country, and status. Accuracy scores, opening repertoires, and per-game breakdowns are not exposed by this endpoint. You can fork this API on Parse and revise it to pull from Chess.com's per-player stats endpoint to add those fields.