Chesscom Published-Data API

The PubAPI is a read-only REST API that responds with JSON-LD data. The API re-packages public data from the website and makes it available via the PubAPI. “Public Data” is information available to people who are not logged in, such as player data, game data, and club/tournament information. This excludes private information that is restricted to the logged in user, such as game chat and conditional moves.

This is read-only data. You cannot send game-moves or other commands to Chess.com from this system.

To use the PubAPI:

  1. Determine the data you want, and compose the URL for it based on the endpoint URL pattern
  2. Request that URL in your browser, program, Postman, cURL, or pigeon
  3. Enjoy the JSON

This page is the documentation for the PubAPI. Please keep the comments focused on the documentation itself, and use the Club Forums to discuss suggestions, bug reports, and how you use the data!

Table of Contents

General Use Features and Issues

The format for each endpoint will be different and is 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 and understand all of these before starting any significant work.

Cache Invalidation: Endpoints refresh at most once every 12 hours.

Data Currency (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 delivered. We expect to remove the option of using v2 in the coming months. Until then, inform your users that data accuracy will improve if they and their opponents are all using the new v3 website.

This issue does not apply to mobile app users.

Language: English

URL responses are identical for everyone, regardless of location. This speeds up delivery but means that any text (for example, reasons for game ending or error responses) will be in English.

Rate Limiting

Your serial access rate is unlimited. If you wait for the response to your previous request before making the next, you should not encounter rate limiting.

However, if you make parallel requests (for example, in a threaded application or a multi-request webserver), some requests may be blocked based on server load. Be prepared to accept a 429 Too Many Requests response for non-serial requests.

In cases of abnormal or suspicious activity, we may block your application entirely. If you supply a recognizable user-agent containing contact information, we will attempt to contact you to correct any issues before blocking your application.

How to Get the PubAPI Data

The PubAPI endpoints can be accessed by any client or browser that supports the HTTP protocol.

For a quick test, simply enter the endpoint URL (for example, the Profile endpoint) in your browser’s address bar to see what happens.

The response is compressed, so consider using tools such as this online JSON formatter to view it in a more readable format.

If you prefer a Command Prompt/Terminal, you can use the curl command. For example,

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

will return useful data such as the response code, ETag, date, and last-modified headers that help determine if you are receiving fresh or cached data. To manipulate JSON from curl, consider using jq as shown in these examples by @pmaugeri.

If command-line tools aren’t your preference, free online tools like Postman and Insomnia provide a user-friendly interface. We have released a collection of endpoints for these tools, available for download from HERE. Instructions for importing collections can be found in the Postman docs or Insomnia docs.

All time fields are expressed as a “timestamp” (seconds since the Unix Epoch: January 1, 1970 00:00:00 GMT). Use your language’s functions or online converters such as this converter to convert timestamps to human-readable dates.

HTTP Response Codes

Response codes inform your client about the state of the requested data.

  • 200: Enjoy your JSON!
  • 301: The URL is outdated; your client should update to the new URL.
  • 304: The data has not changed since your last request (via ETag/If-None-Match or Last-Modified/If-Modified-Since).
  • 404: The URL is malformed or the requested data does not exist (e.g., a non-existent username).
  • 410: No data will ever be available at the requested URL; do not request again.
  • 429: Rate limit exceeded; see the Rate Limiting section above.

JSON-LD

We provide “linked data” contexts for each JSON data format. JSON-LD is fully compatible with JSON, and we include an HTTP Link header that points to the JSON-LD context for the format. For more information, see the JSON-LD documentation or refer to the specification.

JSONP

JSONP, or “JSON with padding,” allows you to supply a callback parameter in the query string. The API then wraps the JSON response in a function call with that name. This is useful when loading data via a <script> tag. For example:

Note: JSONP function names with non-literal characters or longer than 200 characters will be removed from the response.

Caching

Every response includes ETag and Last-Modified headers. If your request includes the proper caching headers (If-None-Match or If-Modified-Since), you may receive a 304 Not Modified response indicating your cached data is still valid.

If you request data more frequently than the Cache-Control header’s max-age value, our CDN may serve cached responses. You might see headers indicating a cache “HIT”, “MISS”, “EXPIRED”, or “REVALIDATED”.

Note: Endpoints refresh at most once every 24 hours unless otherwise specified.

HTTP Compression & HTTP/2

If the request includes an Accept-Encoding: gzip header, responses larger than approximately 200 bytes will be gzip compressed, saving up to 80% of download bandwidth.

HTTP/2 requests receive HTTP/2 responses, which include header compression, binary transfer, and multiplexed responses. However, be mindful of the aforementioned rate limits on parallel requests.

Endpoints

Player Profile

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

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

Data Format:

{ "@id": "URL", // self-referencing URL of this profile "url": "URL", // Chess.com user's profile page (username with original case) "username": "string", // player's username "player_id": 41, // Chess.com unique, non-changing player ID "title": "string", // (optional) chess title abbreviation "status": "string", // account status: closed, closed:fair_play_violations, basic, premium, mod, staff "name": "string", // (optional) player's full name "avatar": "URL", // (optional) URL of a 200x200 image "location": "string", // (optional) city or location "country": "URL", // API URL for this player's country profile "joined": 1178556600, // registration timestamp on Chess.com "last_online": 1500661803, // timestamp of last login "followers": 17, // number of followers "is_streamer": "boolean", // indicates if the member is a Chess.com streamer "twitch_url": "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 to help determine when a username has changed. If a Player Profile retrieved by a username-based URL (from a Game or other object) has a “player_id” that matches a previously downloaded profile, assume the new profile replaces the old one. All URLs for the previous username will now be found under the new username. This is rare, and while the “player_id” will never change for a given account, its future availability is not guaranteed.

Titled Players

Description: List of usernames for players with a specific title.

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

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

Data Format:

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

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

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

Player Stats

Description: Get ratings, win/loss records, and other stats for gameplay, tactics, lessons, and Puzzle Rush.

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

The response contains multiple stats objects, each keyed by a rating type (composed of the rules code and time-class code, separated by an underscore). If a player hasn’t played a game type, that stats object will be absent.

{ "chess_daily": { /* stats object for standard daily chess */ }, "chess960_daily": { /* stats object for Chess960 daily chess */ }, "chess_blitz": { /* stats object for blitz chess */ }, "tactics": { "highest": { "rating": "integer", "date": "timestamp" }, "lowest": { "rating": "integer", "date": "timestamp" } }, "lessons": { "highest": { "rating": "integer", "date": "timestamp" }, "lowest": { "rating": "integer", "date": "timestamp" } }, "puzzle_rush": { "daily": { "total_attempts": "integer", "score": "integer" }, "best": { "total_attempts": "integer", "score": "integer" } } }

Each game-type stats object includes only collected, non-default information. For instance, if a player has no wins in a game type, the “best” stats will not be present. Similarly, tournament stats are omitted if not applicable. Tactics, Lessons, and Puzzle Rush stats may be missing depending on player activity.

Data Format for Each Game-Type:

{ "last": { // current stats "date": 1509709165, // timestamp of last rated game finished "rating": 1642, // current rating "rd": 58 // Glicko "RD" value for rating changes }, "best": { // best rating achieved by a win "date": 1256228875, // timestamp of best-win game "rating": 2065, // highest rating achieved "game": "URL" // URL of best-win game }, "record": { // game record summary "win": 177, "loss": 124, "draw": 21, "time_per_move": 18799, // average seconds per move "timeout_percent": 9.99 // timeout percentage over the last 90 days }, "tournament": { // tournament participation summary "count": 20, "withdraw": 1, "points": 39, "highest_finish": 1 } }

JSON-LD Context: in progress

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

Player Online Status

Description: Indicates whether 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 if online, false otherwise }

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

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

Current Daily Chess

Description: An 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", // URL of the white player's profile "black": "string", // URL of the black player's profile "url": "string", // URL of the game "fen": "string", // current FEN "pgn": "string", // current PGN "turn": "black", // player to move "move_by": 1501765498, // timestamp for the next move; "0" if the player-to-move is on vacation "draw_offer": "black", // (optional) player who made a draw offer "last_activity": 1509810789, // timestamp of last game activity "start_time": 1254438881, // game start timestamp (Daily Chess only) "time_control": "string", // PGN-compliant time control "time_class": "string", // rating time-class (e.g., daily, blitz) "rules": "string", // game variant information (e.g., "chess960") "tournament": "string", // URL to tournament (if available) "match": "string" // URL to team match (if available) } ] }

JSON-LD Contexts: ChessGames.jsonld and ChessGame.jsonld

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

To-Move Daily Chess

Description: An 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", // URL of the game "move_by": 1254438881, // timestamp for the required move; "0" if not the player's turn "draw_offer": true, // (optional) indicates a draw offer was received "last_activity": 1509810789 // timestamp of last game activity } ] }

Note: Some games where it is not the player’s turn may appear if a draw offer is pending. In such cases, move_by is “0”, and the game is sorted to the top for immediate action.

JSON-LD Contexts: ChessGames.jsonld and ChessGame.jsonld

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

List of Monthly Archives

Description: An array of monthly archives available for a player.

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

Data Format:

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

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

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

Complete Monthly Archives

Description: An array of Live and Daily Chess games that a player has completed.

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

  • YYYY: 4-digit year
  • MM: 2-digit month

Data Format for Each Game:

{ "white": { "username": "string", // white player's username "rating": 1492, // white player's rating after game completion "result": "string", // see Game Results Codes "@id": "string" // URL to white player's profile }, "black": { "username": "string", // black player's username "rating": 1942, // black player's rating after game completion "result": "string", // see Game Results Codes "@id": "string" // URL to black player's profile }, "accuracies": { "white": float, "black": float }, "url": "string", // URL of the game "fen": "string", // final FEN "pgn": "string", // final PGN "start_time": 1254438881, // start timestamp (Daily Chess only) "end_time": 1254670734, // game end timestamp "time_control": "string", // PGN-compliant time control "rules": "string", // game variant (e.g., "chess960") "eco": "string", // URL to ECO opening (if available) "tournament": "string", // URL to tournament (if available) "match": "string" // URL to team match (if available) }

JSON-LD Contexts: ChessGames.jsonld and ChessGame.jsonld

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

Complete Live Archive by Time Control

Description: An array of Live Chess games that a player has completed, filtered by time control.

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

  • BASETIME: Base time in seconds
  • INCREMENT: Increment in seconds

Data Format for Each Game:

{ "games": [ { "url": "string", // URL of the game "pgn": "string", // final PGN "time_control": "string", // PGN-compliant time control "end_time": 1277170171, // game end timestamp "rated": boolean, // whether the game was rated "accuracies": { "white": float, "black": float }, "fen": "string", // final FEN "time_class": "blitz", "rules": "string", // game variant (e.g., "chess960") "white": { "username": "string", // white player's username "rating": 1661, "result": "string", // see Game Results Codes "@id": "string", "uuid": "fe696c00-fcba-11db-8029-000000000000" }, "black": { "username": "string", // black player's username "rating": 1577, "result": "string", // see Game Results Codes "@id": "string", "uuid": "d65c8c3a-5313-11df-805e-000000000000" }, "eco": "string" // URL to ECO opening (if available) } ] }

JSON-LD Contexts: ChessGames.jsonld and ChessGame.jsonld

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

Multi-Game PGN Download

Description: Download a standard multi-game PGN containing all games for a specific month.

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

Data Format: The response follows the PGN standard and is not JSON-encoded. Note the following headers when accessing this endpoint programmatically:

  • Content-Type: application/x-chess-pgn — indicates the parser required for the data
  • Content-Disposition: attachment; filename="ChessCom_username_YYYYMM.pgn" — suggests that the browser download the file with the indicated filename

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

Player’s Clubs

Description: List the clubs a player is a member of, along with join dates and last activity dates.

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

Data Format:

{ "clubs": [ { "@id": "url", // URL of the club endpoint "name": "string", // club name "last_activity": "timestamp", // timestamp of last club activity "icon": "url", // club icon URL "url": "url", // club URL "joined": "timestamp" // timestamp when the player joined the club } ] }

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

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

Player Matches

Description: Lists team matches the player has attended, is participating in, or is registered for.

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

Data Format:

{ "finished": [ { "name": "Name of match", "url": "URL", // match URL on website "@id": "URL", // PubAPI match endpoint URL "club": "URL", // player's club endpoint URL "results": { "played_as_white": "win", // see Game Results Codes "played_as_black": "win" }, "board": "URL" // PubAPI match board endpoint 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 Context: https://api.chess.com/context/PlayerMatches.jsonld

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

Player’s Tournaments

Description: Lists tournaments the player is registered for, is attending, or has attended.

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

Data Format:

{ "finished": [ { "url": "URL", // PubAPI tournament URL "@id": "URL", // website tournament URL "wins": 3, "losses": 5, "draws": 0, "points_awarded": 0, "placement": 4, "status": "eliminated", // final status: winner, eliminated, withdrew, removed "total_players": 5 } ], "in_progress": [ { "url": "URL", // PubAPI tournament URL "@id": "URL", // website tournament URL "status": "eliminated" } ], "registered": [ { "url": "URL", // PubAPI tournament URL "@id": "URL", // website tournament URL "status": "invited" // current status: invited, registered } ] }

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

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

Additional Endpoints

Clubs

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

The url-ID is the same as in the club’s web page URL on www.chess.com. For instance, 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", // self-referencing URL of this profile "name": "string", // human-readable club name "club_id": 57796, // unique, non-changing Chess.com club ID "icon": "URL", // (optional) URL of a 200x200 image "country": "URL", // URL to this club's country profile "average_daily_rating": 1376, // average daily rating "members_count": 54, // total members count "created": 1178556600, // creation timestamp on Chess.com "last_activity": 1500661803, // timestamp of the most recent activity (post, match, etc.) "visibility": "public", // public or private status "join_request": "URL", // URL to submit a join request "admin": [ /* array of URLs to admin player profiles */ ], "description": "string" // text description of the club }

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

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

Club Members

Description: List club members (usernames and join timestamps) grouped by activity frequency. Activity includes actions such as viewing the homepage, news, forums, club settings, tournaments, team matches, or leaderboards. Note: playing a club game does not count.

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

Cache Invalidation: Refreshes at most once every 12 hours.

Data Format:

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

Note: Updates based on join, leave, or ban may lag up to 24 hours for weekly activity.

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

Example: https://api.chess.com/pub/club/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/{url-ID}/matches

Data Format:

{ "finished": [ { "name": "match name", // team match name "@id": "URL", // URL to the team match endpoint "opponent": "URL", // opponent club URL "result": "win", // see Game Results Codes "start_time": 1305324926, // match start timestamp "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 Context: https://api.chess.com/context/ClubMatches.jsonld

Example: https://api.chess.com/pub/club/team-usa-southwest/matches

Tournaments

All tournament-based URLs use the tournament’s url-ID. For example: https://api.chess.com/pub/tournament/{url-ID}

The url-ID is identical to that in the tournament’s webpage on www.chess.com. For instance, the url-ID of this tournament is -33rd-chesscom-quick-knockouts-1401-1600.

Tournament

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

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

Data Format:

{ "name": "name", "url": "URL", // URL to the tournament webpage "description": "description", "creator": "username", // creator's username "status": "finished", // {finished, in_progress, registration} "finish_time": 1251846528, // finish timestamp (if finished) "settings": { "type": "round_robin", "rules": "string", // game variant (e.g., "chess960") "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": "username", "status": "eliminated" // user's status in the tournament } ], "rounds": [ /* array of tournament round URLs */ ] }

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

Example: https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600

Tournament’s Round

Description: Get details about a specific round of a tournament.

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

Data Format:

{ "groups": [ /* array of round group URLs */ ], "players": [ { "username": "username", "is_advancing": false // true or false (if tournament is completed) } ] }

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

Example: https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1

Tournament’s Round Group

Description: Get details about a specific group within a tournament round.

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

Data Format:

{ "fair_play_removals": [ // array of usernames removed for fair play violations ], "games": [ { "white": "string", // URL of white player's profile "black": "string", // URL of black player's profile "url": "string", // game URL "fen": "string", // current FEN "pgn": "string", // current PGN "turn": "black", // player to move "move_by": 1501765498, // next move deadline timestamp ("0" if on vacation) "draw_offer": "black", // (optional) draw offer initiator "last_activity": 1509810789, // last activity timestamp "start_time": 1254438881, // game start timestamp (Daily Chess only) "time_control": "string", // PGN-compliant time control "time_class": "string", // rating time-class "rules": "string", // game variant (e.g., "chess960") "eco": "string", // URL to ECO opening (if available) "tournament": "string" // URL to tournament (if available) } ], "players": [ { "username": "username", "points": 2, // points earned (adjusted for fair play) "tie_break": 6, // tie-break points earned "is_advancing": false // true or false } ] }

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

Example: https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1/1

Team Matches

All team match-based URLs use the match ID as specified on the team match web page. For example: https://api.chess.com/pub/match/{ID}

For example, the match ID of WORLD LEAGUE Round 5: Romania vs USA Southwest is 12803.

Team Match

Description: Get details about a team match and its players. During registration, links to players’ stats endpoints are provided for up-to-date info.

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

Data Format (Registration Phase):

{ "name": "string", "url": "URL", // URL of the match on the website "description": "string", "start_time": timestamp, // manual or automatic start time "settings": { "time_class": "daily", "time_control": "string", "initial_setup": null, // initial board setup (if applicable) "rules": "string", // game variant (e.g., "chess960") "min_team_players": integer, "max_team_players": integer, "min_required_games": integer, "min_rating": integer, "max_rating": integer, "autostart": boolean }, "status": "registration", "boards": integer, // number of boards "teams": { "team1": { "@id": "URL", // API URL for club profile "url": "URL", // Web URL for club profile "name": "string", "score": "score", // team score (adjusted for fair play) "players": [ { "username": "string", "board": "URL", // 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 / 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": "string", // e.g., finished, in_progress "boards": integer, "teams": { "team1": { "@id": "URL", "name": "string", "score": "score", "players": [ { "username": "string", "board": "URL", "stats": "URL", // link to player's stats endpoint "played_as_white": "string", // e.g., win, lose, resign "played_as_black": "string" } ], "fair_play_removals": [ /* array of usernames removed for fair play */ ] }, "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": [ /* array of usernames removed for fair play */ ] } } }

Note: User statistics are not snapshotted; follow each player’s stats link for current data.

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

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

Daily Team Match Board

Description: Get details about a team match board. Only in-progress or finished games are included.

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

Data Format:

{ "board_scores": { "player1": 0.5, // adjusted user score "player2": 1.5 }, "games": [ { "white": { "username": "string", "rating": 1492, "result": "string", // see Game Results Codes "@id": "string", "team": "URL" // club profile URL }, "black": { "username": "string", "rating": 1942, "result": "string", "@id": "string", "team": "URL" }, "accuracies": { "white": float, "black": float }, "url": "string", "fen": "string", "pgn": "string", // final PGN if finished "start_time": 1254438881, "end_time": 1254670734, // if finished "time_control": "string", "time_class": "string", "rules": "string", "eco": "string", "match": "string" // team match URL (if available) } ] }

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

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

Live Team Matches

Live team match URLs use the match ID. For example: https://api.chess.com/pub/match/{ID}

For instance, the ID for Friendly 5+2 is 5833.

Live Team Match

Description: Get details about a scheduled or live team match. Post-match, links to player stats are provided.

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

Data Format (Scheduled):

{ "@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 (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": [ { "username": "guilhermekk", "stats": "https://api.chess.com/pub/player/guilhermekk/stats", "status": "premium", "played_as_white": "win", "played_as_black": "resigned", "board": "https://api.chess.com/pub/match/5833/4" }, { "username": "insan3_7", "stats": "https://api.chess.com/pub/player/insan3_7/stats", "status": "premium", "played_as_black": "checkmated", "played_as_white": "win", "board": "https://api.chess.com/pub/match/5833/1" }, { "username": "jydra21", "stats": "https://api.chess.com/pub/player/jydra21/stats", "status": "basic", "played_as_black": "checkmated", "played_as_white": "insufficient", "board": "https://api.chess.com/pub/match/5833/5" }, { "username": "luisen_17", "stats": "https://api.chess.com/pub/player/luisen_17/stats", "status": "basic", "played_as_white": "win", "played_as_black": "win", "board": "https://api.chess.com/pub/match/5833/2" }, { "username": "over_9000_aka_max", "stats": "https://api.chess.com/pub/player/over_9000_aka_max/stats", "status": "premium", "played_as_white": "win", "played_as_black": "win", "board": "https://api.chess.com/pub/match/5833/6" }, { "username": "rahara1988", "stats": "https://api.chess.com/pub/player/rahara1988/stats", "status": "premium", "played_as_black": "checkmated", "played_as_white": "agreed", "board": "https://api.chess.com/pub/match/5833/3" } ], "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": [ { "username": "25elevin", "stats": "https://api.chess.com/pub/player/25elevin/stats", "status": "premium", "played_as_black": "timeout", "played_as_white": "timeout", "board": "https://api.chess.com/pub/match/5833/2" }, { "username": "alexkotow", "stats": "https://api.chess.com/pub/player/alexkotow/stats", "status": "basic", "played_as_black": "resigned", "played_as_white": "resigned", "board": "https://api.chess.com/pub/match/5833/6" }, { "username": "checkmatemark04", "stats": "https://api.chess.com/pub/player/checkmatemark04/stats", "status": "basic", "played_as_white": "win", "played_as_black": "agreed", "board": "https://api.chess.com/pub/match/5833/3" }, { "username": "sougataghosh", "stats": "https://api.chess.com/pub/player/sougataghosh/stats", "status": "premium", "played_as_white": "win", "played_as_black": "checkmated", "board": "https://api.chess.com/pub/match/5833/1" }, { "username": "stompall", "stats": "https://api.chess.com/pub/player/stompall/stats", "status": "premium", "played_as_white": "win", "played_as_black": "insufficient", "board": "https://api.chess.com/pub/match/5833/5" }, { "username": "vicountvonjames", "stats": "https://api.chess.com/pub/player/vicountvonjames/stats", "status": "basic", "played_as_black": "checkmated", "played_as_white": "win", "board": "https://api.chess.com/pub/match/5833/4" } ], "fair_play_removals": [] } } }

Note: User stats are dynamic. Follow the stats link for current information.

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

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

Countries

All country-based URLs use the country’s 2-character ISO 3166 code (capitalized). For example: https://api.chess.com/pub/country/{iso}

Chess.com also supports some regions not in the ISO list using user-assigned codes. For example:

  • XA: Canary Islands
  • XB: Basque Country
  • XC: Catalonia
  • XE: England
  • XG: Galicia
  • XK: Kosovo
  • XP: Palestine
  • XS: Scotland
  • XW: Wales
  • XX: International

The inclusion or exclusion of any region does not reflect a political stance.

Country Profile

Description: Get additional details about a country.

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

Data Format:

{ "@id": "URL", // self-referencing URL of this profile "name": "string", // human-readable country name "code": "string" // ISO-3166-1 2-character code }

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

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

Country Players

Description: List of usernames for players in this country.

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

Data Format:

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

Note: Complete lists are not available; this returns new registrants and current active players once per day.

Cache Invalidation: Refreshes at most once every 12 hours.

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

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

Country Clubs

Description: List of club profile URLs for clubs in this country.

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

Data Format:

{ "clubs": [ /* array of club profile URLs */ ] }

Note: The meaning of “country” varies among clubs.

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

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

Daily Puzzle

Daily Puzzle

Description: Information about the daily puzzle featured on Chess.com.

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

Data Format:

{ "title": "title", // title of the puzzle "url": "URL", // URL to the puzzle on Chess.com "publish_time": 1513584000, // publish timestamp "fen": "FEN", // FEN string for the puzzle "pgn": "PGN", // PGN string for the puzzle (may include a wink emoji) "image": "URL" // link to the puzzle image }

Note: If publishing the puzzle, include a visible credit link to Chess.com.

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

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

Random Daily Puzzle

Description: Information about a randomly selected daily puzzle.

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

Data Format:

{ "title": "title", // title of the puzzle "url": "URL", // URL to the puzzle on Chess.com "publish_time": 1513584000, // publish timestamp "fen": "FEN", // FEN string "pgn": "PGN", // PGN string (may include a wink emoji) "image": "URL" // link to the puzzle image }

Notes: The puzzle does not change on every request and has about 15 seconds caching latency. If republishing, credit Chess.com.

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

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

Streamers

Streamers

Description: Information about Chess.com streamers.

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

Data Format:

{ "streamers": [ { "username": "string", "avatar": "URL", "twitch_url": "Twitch.tv URL", "url": "URL" // member profile URL } ] }

Note: This endpoint refreshes every 5 minutes.

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

Leaderboards

Description: Top 50 players for various categories including daily and live games, tactics, and lessons.

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

Data Format:

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

Note: The endpoint refreshes when a leaderboard is updated.

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

Game Results Codes

Codes returned by game-related endpoints:

CodeDescription
winWin
checkmatedCheckmated
agreedDraw agreed
repetitionDraw by repetition
timeoutTimeout
resignedResigned
stalemateStalemate
loseLose
insufficientInsufficient material
50moveDraw by 50-move rule
abandonedAbandoned
kingofthehillOpponent king reached the hill
threecheckChecked for the 3rd time
timevsinsufficientDraw by timeout vs insufficient material
bughousepartnerloseBughouse partner lost

Please contribute bug reports, comments, and feature requests in the forums!

Leave a Reply

Your email address will not be published. Required fields are marked *