Chesscom Published-Data API

Table of Contents

• General Use and Features
  • Caveats: data currency, language, rate limits on parallel requests
  • Clients: How to get the PubAPI data
  • Response format: HTTP response codes, JSON-LD
  • Features: JSONP callback wrapping, caching support, compression and HTTP/2 support
• Endpoints
  • Player Data:
    • Profile
    • Titled Players
    • Stats
    • Player online status
    • Games
      • Current Daily Chess
      • Concise To-Move Daily Chess
      • Available Archives
      • Monthly Archives
      • Live Games by Time Control
      • Multi-Game PGN Download
    • Participation:
      • List of clubs
      • Team Matches
      • Tournaments
  • Clubs
    • Club Profile
    • List of members, by activity level
    • Team Matches
  • Tournaments
    • Tournament
    • Tournament round
    • Tournament round's group
  • Team matches
    • Daily Team Match
    • Daily Team Match board
    • Live Team Match
    • Live Team Match board
  • Countries
    • Country Profile
    • List of players
    • List of clubs
  • Daily puzzle
    • Daily puzzle
    • Random daily puzzle
  • Streamers
  • Leaderboards
• Game results codes

General Use Features and Issues

The format for each endpoint will be different, and described in a release note about that endpoint. They all share the following features and issues. Even though you only need a URL to obtain the data, we advise that you read through and understand all of these before you start any significant work.

Cache invalidation

This endpoints refresh at most once every 12 hours

Not (Yet) Guaranteed Current

About 3% of players are still actively using the old "v2" website for some actions. When these players perform an action that modifies the data you are requesting, the data may be out of date when we deliver it to you. We expect to remove the option of using v2 in the coming months. Until then, you can communicate to your users that data accuracy will be improved if they and their opponents are all using the new v3 website.

This issue does not apply to people using the mobile apps.

English

URL responses are the same for everyone, no matter who or where they are. This speeds up delivery, but also means that in cases where the data contain words (for example, reasons for game ending, error responses), these words will be in English.

Rate Limiting

Your serial access rate is unlimited. If you always wait to receive the response to your previous request before making your next request, then you should never encounter rate limiting.

However, if you make requests in parallel (for example, in a threaded application or a webserver handling multiple simultaneous requests), then some requests may be blocked depending on how much work it takes to fulfill your previous request. You should be prepared to accept a "429 Too Many Requests" response from our server for any non-serial request that you make.

In some cases, if we detect abnormal or suspicious activity, we may block your application entirely. If you supply a recognizable user-agent that contains contact information, then if we must block you application we will attempt to contact you to correct the problem.

How to get the PubAPI data

The PubAPI endpoints can be called by any kind of client or browser that supports the HTTP protocol. So if you only want to see what happens when you issue a request to an endpoint, you can open your browser and write in the address bar the endpoint you are interested in (for example the Profile endpoint).

The response is compressed, but there are many tools only that can render that response in a more readable format (for example this JSON formatter).

If you have access to a Command Prompt/Terminal Window you can use the curl command that will give you more useful information. For example the command curl -v https://api.chess.com/pub/player/hikaru will return, among the response, a lot of useful data such as the response code, Etag, date, last-modified that are very useful to check if you are retrieving fresh or cached data.

If you want to play with data retrieved by curl you can use jq as was shown in brilliant examples by @pmaugeri.

If you don't want to deal with command line there are many free tools online that provide an easier user interface. The ones that we use mostly in our team are Postman and Insomnia.

If you use Postman or Insomnia, we have released a collection of endpoints that you can download. After installing the collection you will find all the current endpoints that you can call by a click. If you need instructions on how to import collections, check the documentation for those tools.

All time fields are expressed as "timestamp", which is a number calculated as the time measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). All programming languages have functions to convert timestamps to a human-readable format, but if you want to try by hand you can use one of the many online converters.

HTTP Responses

Response codes are used to tell your client about the state of the data you requests.

• 200 = "enjoy your JSON"
• 301 = if the URL you requested is bad, but we know where it should be; your client should remember and correct this to use the new URL in future requests
• 304 = if your client supports "ETag/If-None-Match" or "Last-Modified/If-Modified-Since" caching headers and the data have not changed since the last request
• 404 = we try to tell you if the URL is malformed or the data requested is just not available (e.g., a username for a user that does not exist)
• 410 = we know for certain that no data will ever be available at the URL you requested; your client should not request this URL again
• 429 = we are refusing to interpret your request due to rate limits; see "Rate Limiting" above

JSON-LD

We provide "linked data" contexts for each of our JSON data formats. JSON-LD can be parsed as regular JSON (it is fully compatible), but we also provide an HTTP header called "Link" which contains a URL to the JSON-LD context for this data format. This helps the data describe its own meaning. You can read more about JSON-LD by reading the spec or searching Google in your language.

JSONP

In JSONP, or "JSON with padding," a callback parameter can be sent in the query string of any URL, and the value will be treated as the name of a function to call with the data as a parameter. This is useful if you want to point to the URL in a <script> tag's src value, instead of calling the URL programmatically in your code. As an example, compare these:

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

JSONP function names containing non-literal chars or longer than 200 chars will be removed from response.

Caching

Each response has "ETag" and "Last-Modified" headers. If your client supplies the proper header in the request to prove that the data have not changed since your previous request (If-None-Match and If-Modified-Since, respectively), then you will receive a 304 Not Modified response code, telling you that it is safe and correct to use your cached version.

If you make a request more frequently than the "Cache-Control" header's "max-age" value, then our CDN may respond to you directly with cached values. At refresh rates greater than specified in the "max-age" value, the CDN will validate the currency of its response before sending it to you. You may see headers indicating a cache "HIT", "MISS", "EXPIRED", or "REVALIDATED" for this purpose.

Please note: The endpoints refresh at most once every 24 hours, if not noted otherwise.

HTTP Compression & HTTP/2

If the request is made with an Accept-Encoding: gzip header, then the response will be gzip compressed for transfer if it is of a size where this saves time (generally, more than 200 bytes). With gzip'd transfers, you can save up to 80% of the download bandwidth for the same data.

HTTP/2 requests will get HTTP/2 responses. For the most part, this means header compression / binary transfer, and multiplexed responses for parallel downloads. However, see above-mentioned rate limits on parallel requests.

Endpoints

Player Data

Profile

Description: Get additional details about a player in a game.

URL pattern: https://api.chess.com/pub/player/{username}

Data format:

{
  "@id": "URL",            // the location of this profile (always self-referencing)
  "url": "URL",            // the chess.com user's profile page
  "username": "string",    // the username of this player
  "player_id": 41,         // the non-changing Chess.com ID of this player
  "title": "string",       // (optional) abbreviation of chess title, if any
  "status": "string",      // account status: closed, closed:fair_play_violations, basic, etc.
  "name": "string",        // (optional) the personal first and last name
  "avatar": "URL",         // (optional) URL of a 200x200 image
  "location": "string",    // (optional) the city or location
  "country": "URL",        // API location of this player's country's profile
  "joined": 1178556600,    // timestamp of registration on Chess.com
  "last_online": 1500661803, // timestamp of the most recent login
  "followers": 17,         // the number of players tracking this player's activity
  "is_streamer": "boolean",// if the member is a Chess.com streamer
  "twitch_url": "string",  // Twitch.tv URL
  "fide": "integer"        // FIDE rating
}

JSON-LD Context: https://api.chess.com/context/Player.jsonld

Example: https://api.chess.com/pub/player/erik

Note: the "player_id" is provided as a convenience to determine when a username has been changed. If you retrieve a Player Profile by the username-based URL linked from a Game or other object, and this new Player Profile has a "player_id" that matches a Profile you previously downloaded, then you can safely assume that this new Profile replaces the old, and all URLs with the previous username will now be found under the new username. This should be an extremely rare occurrence. This "player_id" will never change for a given account, however the future availability of this ID is not guaranteed.

Titled Players

Description: List of titled-player usernames.

URL pattern: https://api.chess.com/pub/titled/{title-abbrev}

Valid title abbreviations are: GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM.

Data Format:

{
  "players": [
    /* array of usernames for players with this title */
  ]
}

JSON-LD Contexts: https://api.chess.com/context/Players.jsonld

Example: https://api.chess.com/pub/titled/GM

Player Stats

Description: Get ratings, win/loss, and other stats about a player's game play, tactics, lessons and Puzzle Rush score.

URL pattern: https://api.chess.com/pub/player/{username}/stats

The response contains many "stats objects," each identified by the ratings-type from the game, composed of the rules code, an underscore, and the time-class code. If a person has not played a particular game type, no stats object will be present for it. Like so:

{
  "chess_daily": { /* stats object */ },
  "chess960_daily": { /* stats object */ },
  "chess_blitz": { /* stats object */ },
  "tactics": { ... },
  "lessons": { ... },
  "puzzle_rush": { ... }
}

Each stats object will contain only information that has been collected and is not "default". For example, if a player has not won any games in a game type, the "best" stats will not be present; if they have not played in tournaments, then the tournaments stats will not be present. Not all stats are collected for all game types, and the available data may change over time. Tactics, Lessons and Puzzle Rush stats may be missing, depending on player activity.

Data Format, each Game-Type example:

{
  "last": { 
    "date": 1509709165, // timestamp of the last rated game finished
    "rating": 1642,     // most-recent rating
    "rd": 58            // the Glicko "RD" value used to calculate ratings changes
  },
  "best": {
    "date": 1256228875,
    "rating": 2065,
    "game": "URL"
  },
  "record": {
    "win": 177,
    "loss": 124,
    "draw": 21,
    "time_per_move": 18799,
    "timeout_percent": 9.99
  },
  "tournament": {
    "count": 20,
    "withdraw": 1,
    "points": 39,
    "highest_finish": 1
  }
}

JSON-LD contexts: in progress

Example: https://api.chess.com/pub/player/erik/stats

Player online status

Description: Tells if a user has been online in the last five minutes.

URL pattern: https://api.chess.com/pub/player/{username}/is-online

Data Format:

{
  "online": boolean //true or false
}

JSON-LD contexts: https://api.chess.com/context/PlayerIsOnline.jsonld

Example: https://api.chess.com/pub/player/erik/is-online

Player Games

There are six endpoints for a player's games: to-move, current, list of available monthly archives, monthly archive, live archive by time control, and downloadable-PGN monthly archive. The to-move, current games, and monthly archive lists use this wrapping data format:

{
  "games": [
    /* array of Game objects in ascending game-end-time order */
  ]
}

If no games were played that period (that month, or "now"), this is an empty array.

These game objects share these element definitions:

• pgn: the PGN representation of the game.
• rules: to indicate chess-variant play. Possible values: "chess", "chess960", etc.
• time_class: speed of the game. Possible values: "daily", "rapid", "blitz", "bullet".
• time_control: specific time control used in the game, in PGN notation.
• last_activity: in currently-playing (daily) games, represents the time of the last action. Omitted in archives, where it equals end_time.

Current Daily Chess

Description: Array of Daily Chess games that a player is currently playing.

URL pattern: https://api.chess.com/pub/player/{username}/games

Data Format:

{
  "games": [
    {
      "white": "string", 
      "black": "string", 
      "url": "string",   
      "fen": "string",   
      "pgn": "string",   
      "turn": "black",   
      "move_by": 1501765498, 
      "draw_offer": "black",
      "last_activity": 1509810789, 
      "start_time": 1254438881, 
      "time_control": "string",
      "time_class": "string",
      "rules": "string",
      "tournament": "string", 
      "match": "string" 
    }
  ]
}

JSON-LD contexts: ChessGames, ChessGame

Example: https://api.chess.com/pub/player/erik/games

To-Move Daily Chess

Description: Array of Daily Chess games where it is the player's turn to act.

URL pattern: https://api.chess.com/pub/player/{username}/games/to-move

Data Format:

{
  "games": [
    {
      "url": "string",
      "move_by": 1254438881,
      "draw_offer": true,
      "last_activity": 1509810789
    }
  ]
}

Note: this list will at times include some games where it is not the player's turn, if a draw offer has been made.

JSON-LD contexts: ChessGames, ChessGame

Example: https://api.chess.com/pub/player/erik/games/to-move

List of Monthly Archives

Description: Array of monthly archives available for this player.

URL pattern: https://api.chess.com/pub/player/{username}/games/archives

Data Format:

{
  "archives": [
    /* array of URLs for monthly archives in ascending chronological order */
  ]
}

JSON-LD contexts: GameArchives

Example: https://api.chess.com/pub/player/erik/games/archives

Complete Monthly Archives

Description: Array of Live and Daily Chess games that a player has finished.

URL pattern: https://api.chess.com/pub/player/{username}/games/{YYYY}/{MM}

• YYYY is the four digit year
• MM is the two-digit month

Data Format, each Game:

{
  "white": {
    "username": "string",
    "rating": 1492,
    "result": "string",
    "@id": "string"
  },
  "black": {
    "username": "string",
    "rating": 1942,
    "result": "string",
    "@id": "string"
  },
  "accuracies": {
    "white": float,
    "black": float
  },
  "url": "string",
  "fen": "string",
  "pgn": "string",
  "start_time": 1254438881,
  "end_time": 1254670734,
  "time_control": "string",
  "rules": "string",
  "eco": "string",
  "tournament": "string",
  "match": "string"
}

JSON-LD contexts: ChessGames, ChessGame

Example: https://api.chess.com/pub/player/erik/games/2009/10

Complete Live Archive by Time Control

Description: Array of Live Chess games that a player has finished by time control.

URL pattern: https://api.chess.com/pub/player/{username}/games/live/{BASETIME}/(INCREMENT)

• BASETIME is the base time control in seconds
• INCREMENT is the increment in seconds

Data Format, each Game:

{
  "games": [
    {
      "url": "string",
      "pgn": "string",
      "time_control": "string",
      "end_time": 1277170171,
      "rated": boolean,
      "accuracies": {
        "white": float,
        "black": float
      },
      "fen": "string",
      "time_class": "blitz",
      "rules": "string",
      "white": {
        "rating": 1661,
        "result": "string",
        "@id": "string",
        "username": "string",
        "uuid": "string"
      },
      "black": {
        "rating": 1577,
        "result": "string",
        "@id": "string",
        "username": "string",
        "uuid": "string"
      },
      "eco": "string"
    }
  ]
}

JSON-LD contexts: ChessGames, ChessGame

Example: https://api.chess.com/pub/player/erik/games/live/180/2

Multi-Game PGN Download

Description: Standard multi-game format PGN containing all games for a month.

URL pattern: https://api.chess.com/pub/player/{username}/games/{YYYY}/{MM}/pgn

Data Format: This download follows the PGN standard, and is not JSON-encoded. The response has special headers:

• Content-Type: application/x-chess-pgn
• Content-Disposition: attachment; filename="ChessCom_username_YYYYMM.pgn"

Example: https://api.chess.com/pub/player/erik/games/2009/10/pgn

Participation

• List of clubs
• Team Matches
• Tournaments

Player's Clubs

Description: List of clubs the player is a member of, with joined date and last activity date.

URL pattern: https://api.chess.com/pub/player/{username}/clubs

Data Format:

{
  "clubs": [
    {
       "@id": "url",
       "name": "string",
       "last_activity": "timestamp",
       "icon": "url",
       "url": "url",
       "joined": "timestamp"
    }
  ]
}

JSON-LD contexts: PlayerClubs

Example: https://api.chess.com/pub/player/erik/clubs

Player Matches

Description: List of Team matches the player has attended, is participating, or is currently registered.

URL pattern: https://api.chess.com/pub/player/{username}/matches

Data Format:

{
  "finished": [
    {
      "name": "Name of match",
      "url": "URL",
      "@id": "URL",
      "club": "URL",
      "results": {
        "played_as_white": "win",
        "played_as_black": "win"
      },
      "board": "URL"
    }
  ],
  "in_progress": [
    {
      "name": "Name of match",
      "url": "URL",
      "@id": "URL",
      "club": "URL",
      "board": "URL"
    }
  ],
  "registered": [
    {
      "name": "Name of match",
      "url": "URL",
      "@id": "URL",
      "club": "URL"
    }
  ]
}

JSON-LD contexts: PlayerMatches

Example: https://api.chess.com/pub/player/erik/matches

Player's Tournaments

Description: List of tournaments the player is registered, is attending, or has attended in the past.

URL pattern: https://api.chess.com/pub/player/{username}/tournaments

Data Format:

{
  "finished": [
    {
      "url": "URL",
      "@id": "URL",
      "wins": 3,
      "losses": 5,
      "draws": 0,
      "points_awarded": 0,
      "placement": 4,
      "status": "eliminated",
      "total_players": 5
    }
  ],
  "in_progress": [
    {
      "url": "URL",
      "@id": "URL",
      "status": "eliminated"
    }
  ],
  "registered": [
    {
      "url": "URL",
      "@id": "URL",
      "status": "invited"
    }
  ]
}

JSON-LD contexts: PlayerTournaments

Example: https://api.chess.com/pub/player/erik/tournaments

Clubs

All club-based URLs use the club's "URL ID" to specify which club you want data for.
https://api.chess.com/pub/club/{url-ID}

The url-ID is the same as found in the URL for the club's web page on www.chess.com. For example, the url-ID of the Chess.com Developer's Club is chess-com-developer-community.

Club Profile

Description: Get additional details about a club.

URL pattern: https://api.chess.com/pub/club/{url-ID}

Data format:

{
  "@id": "URL",
  "name": "string",
  "club_id": 57796,
  "icon": "URL",
  "country": "URL",
  "average_daily_rating": 1376,
  "members_count": 54,
  "created": 1178556600,
  "last_activity": 1500661803,
  "visibility": "public",
  "join_request": "URL",
  "admin": [
    /* array of URLs to the player profiles for the admins of this club */
  ],
  "description": "string"
}

JSON-LD Context: Club.jsonld

Example: https://api.chess.com/pub/club/chess-com-developer-community

Club Members

Description: List of club members (usernames and joined date timestamp), grouped by club-activity frequency (weekly, monthly, all_time).

URL pattern: https://api.chess.com/pub/club/{url-ID}/members

Cache invalidation: This endpoint refreshes at most once every 12 hours

Data Format:

{
  "weekly": [
    {
      "username": "string",
      "joined": "integer"
    }
  ],
  "monthly": [
    {
      "username": "string",
      "joined": "integer"
    }
  ],
  "all_time": [
    {
      "username": "string",
      "joined": "integer"
    }
  ]
}

Note: these lists are only updated based on members joining, leaving, or being banned. A member listed may not be moved to the weekly-active list for up to 24 hours after posting, reading club news, etc.

JSON-LD contexts: ClubMembers

Example: chess-com-developer-community/members

Club Matches

Description: List of daily and club matches, grouped by status (registered, in progress, finished).

URL pattern: https://api.chess.com/pub/club/{ID}/matches

{
  "finished": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "result": "win",
      "start_time": 1305324926,
      "time_class": "daily"
    }
  ],
  "in_progress": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "start_time": 1305324926,
      "time_class": "daily"
    }
  ],
  "registered": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "time_class": "daily"
    }
  ]
}

JSON-LD contexts: ClubMatches

Example: team-usa-southwest/matches

Tournaments

All tournaments-based URLs use the tournament's "URL ID" to specify which tournament you want data for.
https://api.chess.com/pub/tournament/{url-ID}

The url-ID is the same as found in the URL for the tournament's web page on www.chess.com.

Tournament

Description: Get details about a daily, live and arena tournament.

URL pattern: https://api.chess.com/pub/tournament/{url-ID}

Data format:

{
    "name": "string",
    "url": "URL",
    "description": "string",
    "creator": "string",
    "status": "finished", 
    "finish_time": 1251846528,
    "settings": {
        "type": "round_robin",
        "rules": "string",
        "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": "string",
            "status": "eliminated"
        }
    ],
    "rounds": [
        /* array of tournament's rounds URL */
    ]
}

JSON-LD Context: Tournament.jsonld

Example: Tournament example

Tournament round

Description: Get details about a tournament's round.

URL pattern: https://api.chess.com/pub/tournament/{url-ID}/{round}

Data format:

{
    "groups": [
        /* List of tournament's round groups */
    ],
    "players": [
        {
            "username": "string",
            "is_advancing": false
        }
    ]
}

JSON-LD Context: TournamentRound.jsonld

Example: Tournament Round example

Tournament round's group

Description: Get details about a tournament's round group.

URL pattern: https://api.chess.com/pub/tournament/{url-ID}/{round}/{group}

Data format:

{
    "fair_play_removals":[ 
      //list of username accounts closed for fair play violation
    ],
    "games": [
        {
            "white": "string",
            "black": "string",
            "url": "string",
            "fen": "string",
            "pgn": "string",
            "turn": "black",
            "move_by": 1501765498,
            "draw_offer": "black",
            "last_activity": 1509810789,
            "start_time": 1254438881,
            "time_control": "string",
            "time_class": "string",
            "rules": "string",
            "eco": "string",
            "tournament": "string"
        }
    ],
    "players": [
        {
            "username": "string",
            "points": 2,
            "tie_break": 6,
            "is_advancing": false
        }
    ]
}

JSON-LD Context: TournamentRoundGroup.jsonld

Example: Tournament Round Group example

Team matches

Daily Team Match

Description: Get details about a daily team match and players playing that match.

URL pattern: https://api.chess.com/pub/match/{ID}

Data format (registration phase):

{
    "name": string,
    "url": "URL",
    "description": string,
    "start_time": timestamp,
    "settings": {
      "time_class": "daily",
      "time_control": string,
      "initial_setup": ,
      "rules": string,
      "min_team_players": integer,
      "max_team_players": integer,
      "min_required_games": integer,
      "min_rating": integer,
      "max_rating": integer,
      "autostart": boolean
    },
    "status": "registration",
    "boards": integer,
    "teams": {
        "team1": {
            "@id": "URL",
            "url": "URL",
            "name": "string",
            "score": score,
            "players": [
                {
                    "username": "string",
                    "board": "url",
                    "rating": 1355,
                    "rd": 25.12,
                    "timeout_percent": 25.12,
                    "status": "basic"
                }
            ]
        },
        "team2": {
            "@id": "URL",
            "url": "URL",
            "name": "string",
            "score": score,
            "players": [
                {
                    "username": "string",
                    "board": "url",
                    "rating": 1355,
                    "timeout_percent": 25.21,
                    "status": "basic"
                }
            ]
        }
    }
}

Data format (in progress or finished):

{
    "name": string,
    "url": "URL",
    "description": string,
    "start_time": timestamp,
    "settings": {
      "time_class": "string",
      "time_control": string,
      "rules": string,
      "min_team_players": 0,
      "max_team_players": 0,
      "min_required_games": 0,
      "autostart": false
    },
    "status": "finished" or "in_progress",
    "boards": integer,
    "teams": {
        "team1": {
            "@id": "URL",
            "name": "string",
            "score": score,
            "players": [
                {
                    "username": "string",
                    "board": "url",
                    "stats": "url",
                    "played_as_white": "string",
                    "played_as_black": "string"
                }
            ],
            "fair_play_removals": []
        },
        "team2": {
            "@id": "URL",
            "name": "string",
            "score": score,
            "players": [
                {
                    "username": "string",
                    "board": "url",
                    "stats": "url",
                    "played_as_white": "string",
                    "played_as_black": "string"
                }
            ],
            "fair_play_removals": []
        }
    }
}

JSON-LD Context: Match.jsonld

Example: https://api.chess.com/pub/match/12803

Daily Team match board

Description: Get details about a team match board.

URL pattern: https://api.chess.com/pub/match/{ID}/{board}

Data format:

{
    "board_scores":{
      "player1": 0.5,
      "player2": 1.5
    },
    "games": [
        {
            "white": {
               "username": "string",
               "rating": 1492,
               "result": "string",
               "@id": "string",
               "team": "url"
            },
            "black": {
               "username": "string",
               "rating": 1942,
               "result": "string",
               "@id": "string",
               "team": "url"
            },
            "accuracies": {
              "white": float,
              "black": float
            },
            "url": "string",
            "fen": "string",
            "pgn": "string",
            "start_time": 1254438881,
            "end_time": 1254670734,
            "time_control": "string",
            "time_class": "string",
            "rules": "string",
            "eco": "string",
            "match": "string"
        }
    ]
}

JSON-LD Context: MatchBoard.jsonld

Example: https://api.chess.com/pub/match/12803/1

Live Team Match

Description: Get details about a live team match.

URL pattern: https://api.chess.com/pub/match/live/{ID}

Data format (scheduled example):

{
   "@id":"https://api.chess.com/pub/match/live/5861",
   "name":"Friendly 10|2 Rapid Open: Srbija Tim vs Team USA Live",
   "url":"https://www.chess.com/club/matches/live/5861",
   "start_time":1579988425,
   "status":"scheduled",
   "boards":0,
   "settings":{
      "rules":"chess",
      "time_class":"standard",
      "time_control":600,
      "time_increment":2,
      "min_team_players":1,
      "min_required_games":0,
      "autostart":false
   },
   "teams":{
      "team1":{
         "@id":"https://api.chess.com/pub/club/srbija-tim",
         "name":"Srbija Tim",
         "url":"https://www.chess.com/club/srbija-tim",
         "score":0,
         "players":[],
         "fair_play_removals":[]
      },
      "team2":{
         "@id":"https://api.chess.com/pub/club/team-usa-live",
         "name":"Team USA Live",
         "url":"https://www.chess.com/club/team-usa-live",
         "score":0,
         "players":[],
         "fair_play_removals":[]
      }
   }
}

Data format (match finished):

{
   "@id":"https://api.chess.com/pub/match/live/5833",
   "name":"Friendly 5+2",
   "url":"https://www.chess.com/club/matches/live/5833",
   "start_time":1579471260,
   "end_time":1579472487,
   "status":"finished",
   "boards":6,
   "settings":{
      "rules":"chess",
      "time_class":"blitz",
      "time_control":300,
      "time_increment":2,
      "min_team_players":2,
      "min_required_games":0,
      "autostart":false
   },
   "teams":{
      "team1":{
         "@id":"https://api.chess.com/pub/club/lynx-club",
         "name":"Lynx Club",
         "url":"https://www.chess.com/club/lynx-club",
         "score":7,
         "result":"win",
         "players":[ ... ],
         "fair_play_removals":[]
      },
      "team2":{
         "@id":"https://api.chess.com/pub/club/not-so-pro-chess-league",
         "name":"Not-So PRO Chess League",
         "url":"https://www.chess.com/club/not-so-pro-chess-league",
         "score":5,
         "result":"lose",
         "players":[ ... ],
         "fair_play_removals":[]
      }
   }
}

JSON-LD Context: Match.jsonld

Example: https://api.chess.com/pub/match/live/5833

Live Team match board

Description: Get details about a live team match board.

URL pattern: https://api.chess.com/pub/match/live/{ID}/{board}

Data format:

{
   "board_scores":{
      "stompall":1.5,
      "jydra21":0.5
   },
   "games":[
      {
         "url":"https://www.chess.com/live/game/4415534343",
         "pgn":"PGN of the game",
         "time_control":"300+2",
         "end_time":1579471691,
         "rated":true,
         "fen":"r7/p4pN1/1pn4k/8/2bP3R/2P3R1/6PP/6K1 b - -",
         "time_class":"blitz",
         "rules":"chess",
         "white":{
            "rating":1351,
            "result":"win",
            "@id":"https://api.chess.com/pub/player/stompall",
            "username":"stompall"
         },
         "black":{
            "rating":1458,
            "result":"checkmated",
            "@id":"https://api.chess.com/pub/player/jydra21",
            "username":"JYDRA21"
         },
         "eco":"https://www.chess.com/openings/Kings-Gambit-Accepted-Modern-Defense-4.exd5"
      },
      ...
   ]
}

JSON-LD Context: MatchBoard.jsonld

Example: https://api.chess.com/pub/match/live/5833/5

Countries

All country-based URLs use the country's 2-character ISO 3166 code (capitalized) to specify which country you want data for.
https://api.chess.com/pub/country/{iso}

Country Profile

Description: Get additional details about a country.

URL pattern: https://api.chess.com/pub/country/{iso}

Data format:

{
  "@id": "URL",
  "name": "string",
  "code": "string"
}

JSON-LD Context: Country.jsonld

Example: https://api.chess.com/pub/country/IT

Country Players

Description: List of usernames for players who identify themselves as being in this country.

URL pattern: https://api.chess.com/pub/country/{iso}/players

Data Format:

{
  "players": [
    /* array of usernames */
  ]
}

Cache invalidation: This endpoint refreshes at most once every 12 hours

JSON-LD Context: CountryPlayers

Example: Country Players example

Country Clubs

Description: List of URLs for clubs identified as being in or associated with this country.

URL pattern: https://api.chess.com/pub/country/{iso}/clubs

Data Format:

{
  "clubs": [
    /* array of profile URLs for clubs in this country */
  ]
}

JSON-LD Context: CountryClubs

Example: Country Clubs example

Daily puzzle

Daily puzzle

Description: Information about the daily puzzle found on www.chess.com.

URL pattern: https://api.chess.com/pub/puzzle

Data Format:

{
   "title": "string",
   "url": "URL",
   "publish_time": 1513584000,
   "fen": "FEN",
   "pgn": "PGN",
   "image": "string"
}

Note: If you are going to publish the Daily Puzzle somewhere, please give credits to Chess.com with a visible text link that points to the puzzle page.

JSON-LD Context: DailyPuzzle.jsonld

Example: https://api.chess.com/pub/puzzle

Random daily puzzle

Description: Information about a randomly picked daily puzzle.

URL pattern: https://api.chess.com/pub/puzzle/random

Data Format:

{
   "title": "string",
   "url": "URL",
   "publish_time": 1513584000,
   "fen": "FEN",
   "pgn": "PGN",
   "image":"URL"
}

Note: The puzzle doesn't change every request but has some caching latency.

JSON-LD Context: DailyPuzzle.jsonld

Example: https://api.chess.com/pub/puzzle/random

Streamers

Description: Information about Chess.com streamers.

URL pattern: https://api.chess.com/pub/streamers

Data Format:

{
   "streamers":[
      {
         "username": "string",
         "avatar": "URL",
         "twitch_url": "string",
         "url":"string"
      }
   ]
}

Example: https://api.chess.com/pub/streamers

Leaderboards

Description: Displays information about top 50 players for daily and live games, tactics, and lessons.

URL pattern: https://api.chess.com/pub/leaderboards

Data Format (shortened example):

{
   "daily":[
      {
         "player_id": "integer",
         "@id": "URL",
         "url": "URL",
         "username": "string",
         "score": "integer",
         "rank": "integer"
      }
   ],
   "daily960":[ ... ],
   "live_rapid":[ ... ],
   "live_blitz":[ ... ],
   "live_bullet":[ ... ],
   "live_bughouse":[ ... ],
   "live_blitz960":[ ... ],
   "live_threecheck":[ ... ],
   "live_crazyhouse":[ ... ],
   "live_kingofthehill":[ ... ],
   "lessons":[ ... ],
   "tactics":[ ... ]
}

Example: https://api.chess.com/pub/leaderboards

Game results codes