Introduction

Disclaimer: This mdBook is not an official Chess.com resource. It is an organized and structured version of the Chess.com Public API documentation, created to help me (and maybe also you) access information more quickly.

For the most accurate and up-to-date information, always refer to the official Chess.com API announcement page: Chess.com Published Data API.

The Chess.com Public API (PubAPI) is a read-only REST API that provides access to public data available on the Chess.com website. This includes player data, game data, club information, and more. The API responds with JSON-LD data, making it easy to integrate into various applications.

Key Features

Public Data Only: No private or logged-in user data.
Read-Only: Retrieve data but cannot send moves or commands.
JSON-LD Responses: Data is returned in JSON format with linked data contexts.
Caching: Data is cached and refreshed every 12-24 hours.
Rate Limits: Avoid parallel requests to prevent being blocked.

General Use and Features

How to Use the API

Construct the URL: Use the endpoint patterns provided in the documentation.
Make the Request: Use a browser, cURL, Postman, or any HTTP client.
Parse the Response: Responses are in JSON format.

Rate Limiting

Avoid making parallel requests to prevent being blocked.
If you receive a 429 Too Many Requests response, slow down your requests.

Caching

Data is cached and refreshed every 12-24 hours.
Use ETag and Last-Modified headers to check for updates.

JSON-LD

The API uses JSON-LD (JSON for Linked Data) to provide context for the data. Each response includes a Link header pointing to the JSON-LD context.

JSONP

You can use JSONP by adding a callback parameter to the URL. For example:

https://api.chess.com/pub/player/erik?callback=myFunction

HTTP Compression

Responses are gzip-compressed if the Accept-Encoding: gzip header is included in the request.

HTTP/2 Support

The API supports HTTP/2 for faster and more efficient communication.

Endpoints

This section provides an organized overview of all available endpoints in the Chess.com Public API (PubAPI). Each endpoint is documented with its purpose, URL pattern, and example responses.

[Player Data]
- [Player Profile]
- [Titled Players]
- [Player Stats]
- [Player Online Status]
- [Player Games]
[Clubs]
- [Club Profile]
- [Club Members]
- [Club Matches]
[Tournaments]
- [Tournament]
- [Tournament Round]
- [Tournament Round Group]
[Countries])
- [Country Profile]
- [Country Players]
- [Country Clubs]
[Daily Puzzle]
- [Daily Puzzle]
- [Random Daily Puzzle]
[Streamers]
[Leaderboards]
[Game Results Codes]

Player Data

Player Profile

Endpoint: https://api.chess.com/pub/player/{username}
Response: Returns details like username, title, country, join date, and more.

Example:

{
  "@id": "https://api.chess.com/pub/player/erik",
  "url": "https://api.chess.com/pub/player/erik",
  "username": "erik",
  "player_id": 41,
  "title": "GM",
  "status": "premium",
  "name": "Erik",
  "avatar": "https://images.chesscomfiles.com/uploads/v1/user/12345678.12345678.12345678.12345678.200x200o.1234567890abcdef.jpeg",
  "location": "New York, USA",
  "country": "https://api.chess.com/pub/country/US",
  "joined": 1178556600,
  "last_online": 1500661803,
  "followers": 17,
  "is_streamer": true,
  "twitch_url": "https://twitch.tv/erik",
  "fide": 2800
}

Titled Players

Endpoint: https://api.chess.com/pub/titled/{title-abbrev}
Response: Lists usernames of players with the specified title.

Example:

{
  "players": [
    "erik",
    "hikaru"
  ]
}

Player Stats

Endpoint: https://api.chess.com/pub/player/{username}/stats
Response: Provides ratings, win/loss records, and stats for different game types.

Example:

{
  "chess_daily": {
    "last": {
      "date": 1509709165,
      "rating": 1642,
      "rd": 58
    },
    "best": {
      "date": 1256228875,
      "rating": 2065,
      "game": "https://api.chess.com/pub/player/erik/games/2009/10"
    },
    "record": {
      "win": 177,
      "loss": 124,
      "draw": 21,
      "time_per_move": 18799,
      "timeout_percent": 9.99
    }
  }
}

Player Online Status

Endpoint: https://api.chess.com/pub/player/{username}/is-online
Response: Indicates if the player is currently online.

Example:

{
  "online": true
}

Player Games

Current Daily Games: https://api.chess.com/pub/player/{username}/games
Monthly Archives: https://api.chess.com/pub/player/{username}/games/archives
Download PGN: https://api.chess.com/pub/player/{username}/games/{YYYY}/{MM}/pgn

Clubs

Club Profile

Endpoint: https://api.chess.com/pub/club/{club-url-id}
Response: Provides details like club name, description, member count, and creation date.

Example:

{
  "@id": "https://api.chess.com/pub/club/chess-com-developer-community",
  "name": "Chess.com Developer Community",
  "club_id": 57796,
  "icon": "https://images.chesscomfiles.com/uploads/v1/group/12345678.12345678.12345678.12345678.200x200o.1234567890abcdef.jpeg",
  "country": "https://api.chess.com/pub/country/US",
  "average_daily_rating": 1376,
  "members_count": 54,
  "created": 1178556600,
  "last_activity": 1500661803,
  "visibility": "public",
  "join_request": "https://api.chess.com/pub/club/chess-com-developer-community/join",
  "admin": [
    "https://api.chess.com/pub/player/erik",
    "https://api.chess.com/pub/player/hikaru"
  ],
  "description": "A club for Chess.com developers."
}

Club Members

Endpoint: https://api.chess.com/pub/club/{club-url-id}/members
Response: Lists members grouped by activity level (weekly, monthly, all-time).

Example:

{
  "weekly": [
    {
      "username": "erik",
      "joined": 1178556600
    }
  ],
  "monthly": [
    {
      "username": "hikaru",
      "joined": 1178556600
    }
  ],
  "all_time": [
    {
      "username": "magnus",
      "joined": 1178556600
    }
  ]
}

Tournaments

Tournament

Endpoint: https://api.chess.com/pub/tournament/{url-ID}
Response: Provides details about a tournament.

Example:

{
  "name": "33rd Chess.com Quick Knockouts",
  "url": "https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600",
  "description": "A quick knockout tournament.",
  "creator": "erik",
  "status": "finished",
  "finish_time": 1251846528,
  "settings": {
    "type": "round_robin",
    "rules": "chess",
    "time_class": "daily",
    "time_control": "1/259200",
    "is_rated": true,
    "is_official": false,
    "is_invite_only": false,
    "initial_group_size": 5,
    "user_advance_count": 1,
    "use_tiebreak": true,
    "allow_vacation": false,
    "winner_places": 1,
    "registered_user_count": 5,
    "games_per_opponent": 2,
    "total_rounds": 1,
    "concurrent_games_per_opponent": 1
  },
  "players": [
    {
      "username": "erik",
      "status": "eliminated"
    }
  ],
  "rounds": [
    "https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1"
  ]
}

Countries

Country Profile

Endpoint: https://api.chess.com/pub/country/{iso}
Response: Provides details about a country.

Example:

{
  "@id": "https://api.chess.com/pub/country/US",
  "name": "United States",
  "code": "US"
}

Country Players

Endpoint: https://api.chess.com/pub/country/{iso}/players
Response: Lists usernames of players from the country.

Example:

{
  "players": [
    "erik",
    "hikaru"
  ]
}

Country Clubs

Endpoint: https://api.chess.com/pub/country/{iso}/clubs
Response: Lists clubs associated with the country.

Example:

{
  "clubs": [
    "https://api.chess.com/pub/club/chess-com-developer-community",
    "https://api.chess.com/pub/club/team-usa"
  ]
}

Daily Puzzle

Endpoint: https://api.chess.com/pub/puzzle
Response: Provides information about the daily puzzle.

Example:

{
  "title": "Daily Puzzle",
  "url": "https://www.chess.com/puzzle",
  "publish_time": 1513584000,
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6",
  "image": "https://images.chesscomfiles.com/uploads/v1/puzzle/12345678.12345678.12345678.12345678.200x200o.1234567890abcdef.jpeg"
}

Random Daily Puzzle

Endpoint: https://api.chess.com/pub/puzzle/random
Response: Provides information about a random daily puzzle.

Example:

{
  "title": "Random Puzzle",
  "url": "https://www.chess.com/puzzle/random",
  "publish_time": 1513584000,
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6",
  "image": "https://images.chesscomfiles.com/uploads/v1/puzzle/12345678.12345678.12345678.12345678.200x200o.1234567890abcdef.jpeg"
}

Streamers

Endpoint: https://api.chess.com/pub/streamers
Response: Lists Chess.com streamers.

Example:

{
  "streamers": [
    {
      "username": "erik",
      "avatar": "https://images.chesscomfiles.com/uploads/v1/user/12345678.12345678.12345678.12345678.200x200o.1234567890abcdef.jpeg",
      "twitch_url": "https://twitch.tv/erik",
      "url": "https://api.chess.com/pub/player/erik"
    }
  ]
}

Leaderboards

Endpoint: https://api.chess.com/pub/leaderboards
Response: Lists top 50 players in various categories.

Example:

{
  "daily": [
    {
      "player_id": 123,
      "@id": "https://api.chess.com/pub/player/erik",
      "url": "https://api.chess.com/pub/player/erik",
      "username": "erik",
      "score": 100,
      "rank": 1
    }
  ],
  "daily960": [
    {
      "player_id": 456,
      "@id": "https://api.chess.com/pub/player/hikaru",
      "url": "https://api.chess.com/pub/player/hikaru",
      "username": "hikaru",
      "score": 95,
      "rank": 2
    }
  ]
}

Game Results Codes

Code	Description
win	Win
checkmated	Checkmated
agreed	Draw agreed
repetition	Draw by repetition
timeout	Timeout
resigned	Resigned
stalemate	Stalemate
lose	Lose
insufficient	Insufficient material
50move	Draw by 50-move rule
abandoned	Abandoned
kingofthehill	Opponent king reached the hill
threecheck	Checked for the 3rd time
timevsinsufficient	Draw by timeout vs insufficient material
bughousepartnerlose	Bughouse partner lost

Example Requests

Get Player Profile

curl -v https://api.chess.com/pub/player/erik

Get Daily Puzzle

curl -v https://api.chess.com/pub/puzzle

Get Leaderboards

curl -v https://api.chess.com/pub/leaderboards

Chess.com PubAPI Documentation