Skip to content

Instantly share code, notes, and snippets.

@smilesrg

smilesrg/pubapi_docs.html

Forked from andreij/pubapi_docs.html
Last active June 24, 2019 14:58
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save smilesrg/cd01c37907d0fe8efdac8ee9e25885d2 to your computer and use it in GitHub Desktop.
Save smilesrg/cd01c37907d0fe8efdac8ee9e25885d2 to your computer and use it in GitHub Desktop.
Download ZIP
Chess.com Published-Data API
Raw
pubapi_docs.html
<p>The PubAPI is a read-only REST API that responds with JSON-LD data. Our goal is to re-package all currently public data from the website and make 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.</p>
<p>This is read-only data. You cannot send game-moves or other commands to Chess.com from this system. If you wish to send commands, you will be interested in the Interactive API releasing later this year.</p>
<p>To use the PubAPI:</p>
<ol>
<li>determine the data you want, and compose the URL for it based on the endpoint URL pattern</li>
<li>request that URL in your browser, program, <a href="https://www.getpostman.com/">Postman</a>, cURL, or <a href="https://en.wikipedia.org/wiki/IP_over_Avian_Carriers">pigeon</a>.</li>
<li>enjoy the JSON <img src="https://www.chess.com/bundles/web/images/icons/smileys/1x/happy.png" srcset="https://www.chess.com/bundles/web/images/icons/smileys/2x/happy.png 2x" title="happy" /></li>
</ol>
<p>This page is the documentation for the PubAPI. We will edit this page to make corrections and add new documentation as the API grows. We will date these changes and report them in <a href="https://www.chess.com/clubs/forum/view/changelog">the CHANGELOG</a> so that you can tell what is fresh. Please keep the comments focused on the documentation itself, and use the <a href="https://www.chess.com/clubs/forum/chess-com-developer-community">Club Forums</a> to discuss suggestions, bug reports, and how you use the data!</p>
<hr />
<h3>Table of Contents</h3>
<ul>
<li><a href="#pubapi-general">General Use and Features</a>
<ul>
<li>Caveats: <a href="#pubapi-general-current">data currency</a>, <a href="#pubapi-general-language">language</a>, <a href="#pubapi-general-rate-limits">rate limits on parallel requests</a></li>
<li>Clients: <a href="#pubapi-clients">How to get the PubAPI data</a></li>
<li>Response format: <a href="#pubapi-general-response-codes">HTTP response codes</a>, <a href="#pubapi-general-jsonld">JSON-LD</a></li>
<li>Features: <a href="#pubapi-general-jsonp">JSONP callback wrapping</a>, <a href="#pubapi-general-caching">caching support</a>, <a href="#pubapi-general-gzip">compression and HTTP/2 support</a></li>
</ul>
</li>
<li>Endpoints
<ul>
<li>Player Data:
<ul>
<li><a href="#pubapi-endpoint-player">Profile</a></li>
<li><a href="#pubapi-endpoint-titled">Titled Players</a></li>
<li><a href="#pubapi-endpoint-player-stats">Stats</a></li>
<li><a href="#pubapi-endpoint-player-is-online">Player online status</a></li>
<li><a href="#pubapi-endpoint-games">Games, general</a>. Specific endpoints:
<ul>
<li><a href="#pubapi-endpoint-games-current">Current Daily Chess</a></li>
<li><a href="#pubapi-endpoint-games-tomove">Concise To-Move Daily Chess</a></li>
<li><a href="#pubapi-endpoint-games-archive-list">Available Archives</a></li>
<li><a href="#pubapi-endpoint-games-archive">Monthly Archives</a></li>
<li><a href="#pubapi-endpoint-games-pgn">Multi-Game PGN Download</a></li>
</ul>
</li>
<li>Participation:
<ul>
<li><a href="#pubapi-endpoint-player-clubs">List of clubs</a></li>
<li><a href="#pubapi-endpoint-player-matches">Team Matches</a></li>
<li><a href="#pubapi-endpoint-player-tournaments">Tournaments</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#pubapi-endpoint-club">Clubs</a>:
<ul>
<li><a href="#pubapi-endpoint-club-profile">Club Profile</a></li>
<li><a href="#pubapi-endpoint-club-members">List of members, by activity level</a></li>
<li><a href="#pubapi-endpoint-club-matches">Team Matches</a></li>
</ul>
</li>
<li><a href="#pubapi-endpoint-tournaments">Tournaments</a>:
<ul>
<li><a href="#pubapi-endpoint-tournament-profile">Tournament</a></li>
<li><a href="#pubapi-endpoint-tournament-round">Tournament round</a></li>
<li><a href="#pubapi-endpoint-tournament-round-group">Tournament round's group</a></li>
</ul>
</li>
<li><a href="#pubapi-endpoint-matches">Team matches</a>:
<ul>
<li><a href="#pubapi-endpoint-match-profile">Team Match</a></li>
<li><a href="#pubapi-endpoint-match-board">Team Match board</a></li>
</ul>
</li>
<li><a href="#pubapi-endpoint-country">Countries</a>:
<ul>
<li><a href="#pubapi-endpoint-country-profile">Country Profile</a></li>
<li><a href="#pubapi-endpoint-country-players">List of players</a></li>
<li><a href="#pubapi-endpoint-country-clubs">List of clubs</a></li>
</ul>
</li>
<li>Daily puzzle:
<ul>
<li><a href="#pubapi-daily-puzzle">Daily puzzle</a></li>
<li><a href="#pubapi-random-daily-puzzle">Random daily puzzle</a></li>
</ul>
</li>
<li>Streamers:
<ul>
<li><a href="#pubapi-streamers">Streamers</a></li>
</ul>
</li>
<li>Leaderboards:
<ul>
<li><a href="#pubapi-leaderboards">Leaderboards</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#game-results">Game results codes</a></li>
<li><a href="#pubapi-roadmap">Roadmap</a></li>
</ul>
<p><a id="pubapi-general" name="pubapi-general"></a></p>
<hr />
<h3>General Use Features and Issues</h3>
<p>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.</p>
<p><strong>Cache invalidation:</strong> This endpoints refresh at most once every 12 hours</p>
<p><a id="pubapi-general-current" name="pubapi-general-current"></a></p>
<h6>Not (Yet) Guaranteed Current</h6>
<p>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.</p>
<p>This issue does not apply to people using the mobile apps.</p>
<p><a id="pubapi-general-language" name="pubapi-general-language"></a></p>
<h6>English</h6>
<p>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.</p>
<p><a id="pubapi-general-rate-limits" name="pubapi-general-rate-limits"></a></p>
<h6>Rate Limiting</h6>
<p>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.</p>
<p>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 "<code>429 Too Many Requests</code>" response from our server for any non-serial request that you make.</p>
<p>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.</p>
<p><a id="pubapi-clients" name="pubapi-clients"></a></p>
<h6>How to get the PubAPI data</h6>
<p>The PubAPI endpoints can be called, by any kind of client or browsers that supports the HTTP protocol.</p>
<p>So if you only want to see what happens when you issue a <i>request</i> to an endpoint you can open your browser and write in the address bar the endpoint you are interested in (for example the <a href="https://api.chess.com/pub/player/hikaru">Profile</a> endpoint.</p>
<p>The <i>response</i> is compressed, but there are many tools only that can render that response in a more readable format (gor example <a href="https://jsonformatter.curiousconcept.com" target="_blank" rel="noopener">https://jsonformatter.curiousconcept.com</a>).</p>
<p>If you have access to a Command Prompt/Terminal Window you can use the <code>curl</code> command that will give you more useful information. <br />For example the command "<code>curl -v <a href="https://api.chess.com/pub/player/hikaru">https://api.chess.com/pub/player/hikaru</a></code>" will return, among with the response, a lot of useful data such as the <code>response code</code>, <code>Etag</code>, <code>date</code>, <code>last-modified</code> that are very useful to check if you are retrieving fresh or cached data.<br /> If you want to play with cdata retrieved by <code>curl</code> you can use <a href="https://stedolan.github.io/jq/">jq</a> as was shown in these brilliant <a href="https://www.chess.com/clubs/forum/view/my-firsts-tests-with-chess-com-api-some-examples-with-json-manipulations">examples</a> by @pmaugeri.</p>
<p>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 <a href="https://www.getpostman.com/">Postman</a> and <a href="https://insomnia.rest">Insomnia</a>.</p>
<p>If you use Postman or Insomnia, <b>we have released a collection of endpoints</b> that you can download from <a href="https://www.chess.com/postman/collection-dev.json">HERE</a>. After installing the collection you will find all the current endpoints that you can call by a click (and analyze the response, convert the call into a language of your choice etc.) . If you need instructions on how import collections, check this <a href="https://www.getpostman.com/docs/postman/collections/data_formats">link</a> for Postman or this <a href="https://support.insomnia.rest/article/52-importing-and-exporting-data">link</a> for Insomnia.</p>
<p>All time fields are expressed as "timestamp", which is a number calculated as the time measured in the number of <b>seconds</b> since the Unix Epoch (January 1 1970 00:00:00 GMT). All programming languages have functions to convert timestamps to an human-readable format, but if you want to try by hand you can use one of the many <a href="https://www.epochconverter.com" target="_blank">online converters</a>.</p>
<p><a id="pubapi-general-response-codes" name="pubapi-general-response-codes"></a></p>
<h6>HTTP Responses</h6>
<p>Response codes are used to tell your client about the state of the data you requests.</p>
<ul>
<li><code>200 =</code> "enjoy your JSON"</li>
<li><code>301 =</code> 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</li>
<li><code>304 =</code> if your client supports "<code>ETag/If-None-Match</code>" or "<code>Last-Modified/If-Modified-Since</code>" caching headers and the data have not changed since the last request</li>
<li><code>404 =</code> 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)</li>
<li><code>410 =</code> we know for certain that no data will ever be available at the URL you requested; your client should not request this URL again</li>
<li><code>429 =</code> we are refusing to interpret your request due to rate limits; see "<a href="#pubapi-general-rate-limits">Rate Limiting</a>" above</li>
</ul>
<p><a id="pubapi-general-jsonld" name="pubapi-general-jsonld"></a></p>
<h6>JSON-LD</h6>
<p>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 <a href="https://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld">an HTTP header called "<code>Link</code>"</a> 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 <a href="https://json-ld.org/spec/latest/json-ld/">JSON-LD by reading the spec</a> or searching Google in your language.</p>
<p><a id="pubapi-general-jsonp" name="pubapi-general-jsonp"></a></p>
<h6>JSONP</h6>
<p>In <a href="https://en.wikipedia.org/wiki/JSONP">JSONP, or "JSON with padding,"</a> a "<code>callback</code>" 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 &lt;script&gt; tag's src value, instead of calling the URL programmatically in your code. As an example, compare these:</p>
<ul>
<li><a href="https://api.chess.com/pub/player/erik">https://api.chess.com/pub/player/erik</a></li>
<li><a href="https://api.chess.com/pub/player/erik?callback=myJavascriptFunction">https://api.chess.com/pub/player/erik?callback=myJavascriptFunction</a></li>
</ul>
<p><a id="pubapi-general-caching" name="pubapi-general-caching"></a></p>
<h6>Caching</h6>
<p>Each response has "<code>ETag</code>" and "<code>Last-Modified</code>" headers. If your client supplies the proper header in the request to prove that the data have not changed since your previous request ("<code>If-None-Match</code>" and "<code>If-Modified-Since</code>", respectively), then you will receive a <code>304 Not Modified</code> response code, telling you that it is safe and correct to use your cached version.</p>
<p>If you make a request more frequently than the "<code>Cache-Control</code>" 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.</p>
<p><strong>Please note:</strong> The endpoints refresh at most once every 24 hours, if not noted otherwise.</p>
<p><a id="pubapi-general-caching" name="pubapi-general-gzip"></a></p>
<h6>HTTP Compression &amp; HTTP/2</h6>
<p>If the request is made with an "<code>Accept-Encoding: gzip</code>" 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.</p>
<p>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 <a href="#pubapi-general-rate-limits">above-mentioned rate limits on parallel requests</a>.</p>
<hr />
<h3>Endpoints</h3>
<p><a id="pubapi-endpoint-player" name="pubapi-endpoint-player"></a></p>
<h6>Player Profile</h6>
<p><strong>Description:</strong> Get additional details about a player in a game. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username} <br /> <strong>Data format:</strong></p>
<pre>{
"@id": "URL", // the location of this profile (always self-referencing)
"url": "URL", // the chess.com user's profile page (the username is displayed with the original letter case)
"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, premium, mod, staff
"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": "Twitch.tv URL"
}
</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/Player.jsonld">https://api.chess.com/context/Player.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik">https://api.chess.com/pub/player/erik</a></p>
<p><em>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.</em></p>
<p><a id="pubapi-endpoint-titled" name="pubapi-endpoint-titled"></a></p>
<h6>Titled Players</h6>
<p><strong>Description:</strong> List of titled-player usernames. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/titled/">https://api.chess.com/pub/titled/</a>{title-abbrev}</p>
<p>Valid title abbreviations are: GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM.</p>
<p><strong>Data Format:</strong></p>
<pre>{
"players": [
/* array of usernames for players with this title */
]
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/Players.jsonld">https://api.chess.com/context/Players.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/titled/GM">https://api.chess.com/pub/titled/GM</a></p>
<p><a id="pubapi-endpoint-player-stats" name="pubapi-endpoint-player-stats"></a></p>
<h6>Player Stats</h6>
<p><strong>Description:</strong> Get ratings, win/loss, and other stats about a player's game play, tactics, lessons and Puzzle Rush score. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/stats</p>
<p>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:</p>
<pre>{
"chess_daily": {
/* stats object for games of rules "chess" and "daily" time-class */
},
"chess960_daily": {
/* stats object for games of rules "chess960" and "daily" time-class */
},
"chess_blitz": {
/* stats object for games of rules "chess" and "blitz" time-class */
},
"fide": 2344, /* FIDE rating, integer value */
"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"
}
}
}
</pre>
<p>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 from time to time as we gather more information. Tactics, Lessons and Puzzle Rush stats may be missing, depending on player activity.</p>
<p><strong>Data Format, each Game-Type:</strong></p>
<pre>{
"last": { // the current stats
"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": { // the best rating achieved by a win
"date": 1256228875, // timestamp of the best-win game
"rating": 2065, // highest rating achieved
"game": "URL" // URL of the best-win game
},
"record": { // summary of all games played
"win": 177, // number of games won
"loss": 124, // number of games lost
"draw": 21, // number of games drawn
"time_per_move": 18799, // integer number of seconds per average move
"timeout_percent": 9.99 // timeout percentage in the last 90 days
},
"tournament": { // summary of tournaments participated in
"count": 20, // number of tournaments joined
"withdraw": 1, // number of tournaments withdrawn from
"points": 39, // total number of points earned in tournaments
"highest_finish": 1 // best tournament place
}
}
</pre>
<p><strong>JSON-LD contexts:</strong> <em>in progress</em> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/stats">https://api.chess.com/pub/player/erik/stats</a></p>
<p><a id="pubapi-endpoint-player-is-online" name="pubapi-endpoint-player-is-online"></a></p>
<hr />
<h6>Player online status</h6>
<p><strong>Description:</strong> Tells if an unser has been online in the last five minutes. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/is-online</p>
<p><strong>Data Format:</strong></p>
<pre>{
"online": boolean, //true or false
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/PlayerIsOnline.jsonld">https://api.chess.com/context/PlayerIsOnline.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/is-online">https://api.chess.com/pub/player/erik/is-online</a></p>
<p><a id="pubapi-endpoint-games" name="pubapi-endpoint-games"></a></p>
<hr />
<h6>Player Games</h6>
<p>There are five endpoints for a player's games: to-move, current, list of available monthly archives, monthly archive, and downloadable-PGN monthly archive. The to-move, current games, and monthly archive lists use this wrapping data format:</p>
<pre>{
"games": [
/* array of Game objects in ascending game-end-time order */
]
}
</pre>
<p>If no games were played that period (that month, or "now"), this is an empty array.</p>
<p>These game objects share these element definitions:</p>
<ul>
<li><code>pgn</code>: the PGN representation of the game.</li>
<li><code>rules</code>: to indicate chess-variant play. Possible values are: "chess", "chess960", "bughouse", "kingofthehill", "threecheck", "crazyhouse"</li>
<li><code>time_class</code>: ratings-group speed of the game. Possible values are: "daily", "rapid", "blitz", "bullet".</li>
<li><code>time_control</code>: specific time control used in the game, in <a href="http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm#c9.6">the PGN standard notation</a>.</li>
<li><code>last_activity</code>: in currently-playing (daily) games, this timestamp represents the time of the last action affecting the game. This may be a move, draw offer, or even a deactivation of the chat window. Omitted in archives, where it is synonymous with the <code>end_time</code>.</li>
</ul>
<p><a id="pubapi-endpoint-games-current" name="pubapi-endpoint-games-current"></a></p>
<hr />
<h6>Current Daily Chess</h6>
<p><strong>Description:</strong> Array of Daily Chess games that a player is currently playing. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/games</p>
<p><strong>Data Format:</strong></p>
<pre>{
"games": [
{
"white": "string", // URL of the white player's profile
"black": "string", // URL of the black player's profile
"url": "string", // URL of this game
"fen": "string", // current FEN
"pgn": "string", // current PGN
"turn": "black", // player to move
"move_by": 1501765498, // timestamp of when the next move must be made
// this is "0" if the player-to-move is on vacation
"draw_offer": "black", // (optional) player who has made a draw offer
"last_activity": 1509810789, // timestamp of the last activity on the game
"start_time": 1254438881, // timestamp of the game start (Daily Chess only)
"time_control": "string", // PGN-compliant time control
"time_class": "string", // time-per-move grouping, used for ratings
"rules": "string", // game variant information (e.g., "chess960")
"tournament": "string", //URL pointing to tournament (if available),
"match": "string" //URL pointing to team match (if available)
}
]
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/ChessGames.jsonld">https://api.chess.com/context/ChessGames.jsonld</a>, <a href="https://api.chess.com/context/ChessGame.jsonld">https://api.chess.com/context/ChessGame.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/games">https://api.chess.com/pub/player/erik/games</a></p>
<p><a id="pubapi-endpoint-games-tomove" name="pubapi-endpoint-games-tomove"></a></p>
<hr />
<h6>To-Move Daily Chess</h6>
<p><strong>Description:</strong> Array of Daily Chess games where it is the player's turn to act. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/games/to-move</p>
<p><strong>Data Format:</strong></p>
<pre>{
"games": [
{
"url": "string", // URL of this game
"move_by": 1254438881, // timestamp of the when the move must be made by
// this is "0" if it is not this player's turn
"draw_offer": true, // (optional) this player has received a draw offer
"last_activity": 1509810789, // timestamp of the last activity on the game
}
]
}
</pre>
<p><strong>Note:</strong> this list will at times include some games where it is not the player's turn, if a draw offer has been made. In these cases, the <code>move_by</code> value is "0", and the game is sorted to the top to represent possible immediate action before the other player moves. Sorting is normally based on how soon a move must be made by.</p>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/ChessGames.jsonld">https://api.chess.com/context/ChessGames.jsonld</a>, <a href="https://api.chess.com/context/ChessGame.jsonld">https://api.chess.com/context/ChessGame.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/games/to-move">https://api.chess.com/pub/player/erik/games/to-move</a></p>
<p><a id="pubapi-endpoint-games-archive-list" name="pubapi-endpoint-games-archive-list"></a></p>
<hr />
<h6>List of Monthly Archives</h6>
<p><strong>Description:</strong> Array of monthly archives available for this player. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/games/archives</p>
<p><strong>Data Format:</strong></p>
<pre>{
"archives": [
/* array of URLs for monthly archives in ascending chronological order */
]
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/GameArchives.jsonld">https://api.chess.com/context/GameArchives.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/games/archives">https://api.chess.com/pub/player/erik/games/archives</a></p>
<p><a id="pubapi-endpoint-games-archive" name="pubapi-endpoint-games-archive"></a></p>
<hr />
<h6>Complete Monthly Archives</h6>
<p><strong>Description:</strong> Array of Live and Daily Chess games that a player has finished. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/games/{YYYY}/{MM}</p>
<ul>
<li>"YYYY" is the four digit year of the game-end</li>
<li>"MM" is the two-digit month</li>
</ul>
<p><strong>Data Format, each Game:</strong></p>
<pre>{
"white": { // details of the white-piece player:
"username": "string", // the username
"rating": 1492, // the player's rating at the start of the game
"result": "string", // see "Game results codes" section
"@id": "string", // URL of this player's profile
},
"black": { // details of the black-piece player:
"username": "string", // the username
"rating": 1942, // the player's rating at the start of the game
"result": "string", // see "Game results codes" section
"@id": "string", // URL of this player's profile
},
"url": "string", // URL of this game
"fen": "string", // final FEN
"pgn": "string", // final PGN
"start_time": 1254438881, // timestamp of the game start (Daily Chess only)
"end_time": 1254670734, // timestamp of the game end
"time_control": "string", // PGN-compliant time control
"rules": "string", // game variant information (e.g., "chess960")
"eco": "string", //URL pointing to ECO opening (if available),
"tournament": "string", //URL pointing to tournament (if available),
"match": "string", //URL pointing to team match (if available)
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/ChessGames.jsonld">https://api.chess.com/context/ChessGames.jsonld</a>, <a href="https://api.chess.com/context/ChessGame.jsonld">https://api.chess.com/context/ChessGame.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/games/2009/10">https://api.chess.com/pub/player/erik/games/2009/10</a></p>
<p><a id="pubapi-endpoint-games-pgn" name="pubapi-endpoint-games-pgn"></a></p>
<hr />
<h6>Multi-Game PGN Download</h6>
<p><strong>Description:</strong> standard multi-game format PGN containing all games for a month. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/games/{YYYY}/{MM}/pgn</p>
<p><strong>Data Format:</strong> this download follows <a href="http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm">the PGN standard</a>, and is not JSON-encoded. The response has two special headers worth noting if programmatically hitting this endpoint (browsers handle these automatically):</p>
<ul>
<li><code>Content-Type: application/x-chess-pgn</code> <br /><em>This content type indicates the type of parser needed to understand the data</em></li>
<li><code>Content-Disposition: attachment; filename="ChessCom_username_YYYYMM.pgn"</code> <br /><em>This disposition indicates that browser should download, not display, the result, and it suggests a filename based on the source archive</em></li>
</ul>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/games/2009/10/pgn">https://api.chess.com/pub/player/erik/games/2009/10/pgn</a></p>
<p><a id="pubapi-endpoint-player-clubs" name="pubapi-endpoint-player-clubs"></a></p>
<h6>Player's Clubs</h6>
<p><strong>Description:</strong> List of clubs the player is a member of, with joined date and last activity date. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/clubs</p>
<p><strong>Data Format:</strong></p>
<pre>{
"clubs": [
{
"url": "https://api.chess.com/pub/club/test",
"joined": 1305310668,
"last_activity": 1305310668
}
]
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/PlayerClubs.jsonld">https://api.chess.com/context/PlayerClubs.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/clubs">https://api.chess.com/pub/player/erik/clubs</a></p>
<p><a id="pubapi-endpoint-player-matches" name="pubapi-endpoint-player-matches"></a></p>
<h6>Player Matches</h6>
<p><strong>Description:</strong> List of Team matches the player has attended, is partecipating or is currently registered. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/matches</p>
<p><strong>Data Format:</strong></p>
<pre>{
"finished": [
/** List of matches */
{
"name": "Name of match",
"url": "URL", // URL of match on web site
"@id": "URL", // URL of PubAPI match endpoint
"club": "URL", // URL of player's club endpoint
"results": [
"played_as_white": "win", //result of game played as white, see "Game results codes" section
"played_as_black": "win" //result of game played as black, see "Game results codes" section
],
"board": "URL", // URL of PubAPI match board endpoint
}
],
"in_progress": [
/** List of matches */
{
"name": "Name of match",
"url": "URL", // URL of match on web site
"@id": "URL", // URL of PubAPI match endpoint
"club": "URL", // URL of player's club endpoint
"board": "URL", // URL of PubAPI match board endpoint
}
],
"registered": [
/** List of matches */
{
"name": "Name of match",
"url": "URL", // URL of match on web site
"@id": "URL", // URL of PubAPI match endpoint
"club": "URL", // URL of player's club endpoint
}
]
}
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/PlayerMatches.jsonld">https://api.chess.com/context/PlayerMatches.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/matches">https://api.chess.com/pub/player/erik/matches</a></p>
<p><a id="pubapi-endpoint-player-tournaments" name="pubapi-endpoint-player-tournaments"></a></p>
<h6>Player's Tournaments</h6>
<p><strong>Description:</strong> List of tournaments the player is registered, is attending or has attended in the past. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/player/">https://api.chess.com/pub/player/</a>{username}/tournaments</p>
<p><strong>Data Format:</strong></p>
<pre>{
"finished": [
{
"url": "URL", // link to the PubAPI URL of the tournament
"@id": "URL", // link to the Web URL of the tournament
"wins": 3, //number of wins
"losses": 5, //number of losses
"draws": 0, //number of draws
"points_awarded": 0, //pints awarded
"placement": 4, //placement
"status": "eliminated", //final status of the player in this tourmanent {winner, eliminated, withdrew, removed}
"total_players": 5 //number of total players
} /* array of finished tournaments */
],
"in_progress": [
{
"url": "URL", // link to the PubAPI URL of the tournament
"@id": "URL", // link to the Web URL of the tournament
"status": "eliminated", //final status of the player in this tourmanent {winner, eliminated, withdrew, removed}
} /* array of in progress tournaments */
],
"registered": [
{
"url": "URL", // link to the PubAPI URL of the tournament
"@id": "URL", // link to the Web URL of the tournament
"status": "invited" //current status of user {invited, registered}
} /* array of registered tournaments */
]
}</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/PlayerTournaments.jsonld">https://api.chess.com/context/PlayerTournaments.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/player/erik/tournaments">https://api.chess.com/pub/player/erik/tournaments</a></p>
<p><a id="pubapi-endpoint-club" name="pubapi-endpoint-club"></a></p>
<h6>Clubs</h6>
<p>All club-based URLs use the club's "URL ID" to specify which club you want data for. <br /> <a href="https://api.chess.com/pub/club/">https://api.chess.com/pub/club/</a>{url-ID}</p>
<p>The <code>url-ID</code> is the same as found in the URL for the club's web page on <a href="http://www.chess.com">www.chess.com</a>. For example, the url-ID of <a href="https://www.chess.com/club/chess-com-developer-community">the Chess.com Developer's Club</a> is <code>chess-com-developer-community</code></p>
<p><a id="pubapi-endpoint-club-profile" name="pubapi-endpoint-club-profile"></a></p>
<h6>Club Profile</h6>
<p><strong>Description:</strong> Get additional details about a club. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/club/">https://api.chess.com/pub/club/</a>{url-ID} <br /> <strong>Data format:</strong></p>
<pre>{
"@id": "URL", // the location of this profile (always self-referencing)
"name": "string", // the human-readable name of this club
"club_id": 57796, // the non-changing Chess.com ID of this club
"icon": "URL", // (optional) URL of a 200x200 image
"country": "URL", // location of this club's country profile
"average_daily_rating": 1376, //average daily rating
"members_count": 54 //total members count
"created": 1178556600, // timestamp of creation on Chess.com
"last_activity": 1500661803, // timestamp of the most recent post, match, etc
"visibility": "public", // whether the club is public or private
"join_request": "URL", // location to submit a request to join this club
"admin": [
/* array of URLs to the player profiles for the admins of this club */
],
"description": "string" // text description of the club
}
</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/Club.jsonld">https://api.chess.com/context/Club.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/club/chess-com-developer-community">https://api.chess.com/pub/club/chess-com-developer-community</a></p>
<p><a id="pubapi-endpoint-club-members" name="pubapi-endpoint-club-members"></a></p>
<h6>Club Members</h6>
<p><strong>Description:</strong> List of club members (usernames and joined date timestamp), grouped by club-activity frequency. The club-activity is one of this actions:</p>
<ul>
<li>Viewing the club homepage</li>
<li>Viewing the clubs news index or a specific news article (but not the notification message received that the news was published)</li>
<li>Viewing the club's forums or a specific forum thread</li>
<li>Changing their club settings, including modifying their membership; for admins, this includes inviting or authorizing new members</li>
<li>Viewing the club's tournament, team match, or votechess lists</li>
<li>Viewing club membership lists or running a related search, or viewing the leaderboards for the club</li>
</ul>
<p><strong>Please note: </strong> playing a club game is not counted as a club-activity. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/club/">https://api.chess.com/pub/club/</a>{url-ID}/members</p>
<p><br /> <strong>Cache invalidation:</strong> This endpoints refresh at most once every 12 hours</p>
<p><strong>Data Format:</strong></p>
<pre>{
"weekly": [
{
"username": "string", //username
"joined": "integer", //timestamp
}
],
"monthly": [
{
"username": "string", //username
"joined": "integer", //timestamp
}
],
"all_time": [
{
"username": "string", //username
"joined": "integer", //timestamp
}
]
}
</pre>
<p><strong>Note:</strong> these lists are only updated based on members joining, leaving, or being banned. A member listed as a monthly-active or "all_time" member may not be moved to the weekly-active list for up to 24 hours after posting, reading club news, or participating in club activities.</p>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/ClubMembers.jsonld">https://api.chess.com/context/ClubMembers.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/club/chess-com-developer-community/members">https://api.chess.com/pub/club/chess-com-developer-community/members</a></p>
<p><a id="pubapi-endpoint-club-matches" name="pubapi-endpoint-club-matches"></a></p>
<h6>Club Matches</h6>
<p><strong>Description:</strong> List of club matches, grouped by status (registered, in progress, finished). <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/club/">https://api.chess.com/pub/club/</a>{ID}/matches</p>
<pre>{
"finished": [
/** List of matches */
{
"name": "match name", //the team match name
"@id": "URL", // URL pointing to the team match endpoint
"opponent": "https://api.chess-dev.com/pub/club/testing-teams", // URL pointing to the opponent club endpoint
"result": "win" // see "Game results codes" section
}
],
"in_progress": [
/** List of matches */
{
"name": "match name", //the team match name
"@id": "URL", // URL pointing to the team match endpoint
"opponent": "https://api.chess-dev.com/pub/club/testing-teams", // URL pointing to the opponent club endpoint
}
],
"registered": [
/** List of matches */
{
"name": "match name", //the team match name
"@id": "URL", // URL pointing to the team match endpoint
"opponent": "https://api.chess-dev.com/pub/club/testing-teams", // URL pointing to the opponent club endpoint
}
]
}
</pre>
<p><strong>JSON-LD contexts:</strong> <a href="https://api.chess.com/context/ClubMatches.jsonld">https://api.chess.com/context/ClubMatches.jsonld</a></p>
<p><strong>Example:</strong> <a href="https://api.chess.com/pub/club/team-usa-southwest/matches">https://api.chess.com/pub/club/team-usa-southwest/matches</a></p>
<p><a id="pubapi-endpoint-tournaments" name="pubapi-endpoint-tournaments"></a></p>
<h6>Tournaments</h6>
<p>All tournaments-based URLs use the tournament's "URL ID" to specify which tournament you want data for. <br /> <a href="https://api.chess.com/pub/tournament/">https://api.chess.com/pub/tournament/</a>{url-ID}</p>
<p>The <code>url-ID</code> is the same as found in the URL for the tournament's web page on <a href="http://www.chess.com">www.chess.com</a>. For example, the url-ID of <a href="https://www.chess.com/tournament/-33rd-chesscom-quick-knockouts-1401-1600">the Chess.com Developer's Club</a> is <code>-33rd-chesscom-quick-knockouts-1401-1600</code></p>
<p><a id="pubapi-endpoint-tournament-profile" name="pubapi-endpoint-tournament-profile"></a></p>
<h6>Tournament</h6>
<p><strong>Description:</strong> Get details about a tournament. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/tournament/">https://api.chess.com/pub/tournament/</a>{url-ID} <br /> <strong>Data format:</strong></p>
<pre>{
"name": "name",
"url": "URL", //url to Web tournament's URL
"description": "description",
"creator": "username", //username of creator
"status": "finished", //status of tournament {finished, in_progress, registration}
"finish_time": 1251846528, //timestamp of finish time, if tournament is finished
"settings": {
"type": "round_robin",
"rules": "string", // game variant information (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": [
/** List of tournament's rounds URL */
{
"username": "username",
"status": "eliminated" //status of user
}
],
"rounds": [
/** List of tournament's rounds URL */
]
}</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/Tournament.jsonld">https://api.chess.com/context/Tournament.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600">https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600</a></p>
<p><a id="pubapi-endpoint-tournament-round" name="pubapi-endpoint-tournament-round"></a></p>
<h6>Tournament's round</h6>
<p><strong>Description:</strong> Get details about a tournament's round. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/tournament/">https://api.chess.com/pub/tournament/</a>{url-ID}/{round} <br /> <strong>Data format:</strong></p>
<pre>{
"groups": [
/** List of tournament's round groups */
],
"players": [
/** List of tournament's round players */
{
"username": "username",
"is_advancing":false // {true, false}, only if this tournament is completed
}
]
}</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/TournamentRound.jsonld">https://api.chess.com/context/TournamentRound.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1">https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1</a></p>
<p><a id="pubapi-endpoint-tournament-round-group" name="pubapi-endpoint-tournament-round-group"></a></p>
<h6>Tournament's round group</h6>
<p><strong>Description:</strong> Get details about a tournament's round group. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/tournament/">https://api.chess.com/pub/tournament/</a>{url-ID}/{round}/{group} <br /> <strong>Data format:</strong></p>
<pre>{
"fair_play_removals":[
//list of username accounts closed for fair play violation
],
"games": [
/** List of group's games */
{
"white": "string", // URL of the white player's profile
"black": "string", // URL of the black player's profile
"url": "string", // URL of this game
"fen": "string", // current FEN
"pgn": "string", // current PGN
"turn": "black", // player to move
"move_by": 1501765498, // timestamp of when the next move must be made
// this is "0" if the player-to-move is on vacation
"draw_offer": "black", // (optional) player who has made a draw offer
"last_activity": 1509810789, // timestamp of the last activity on the game
"start_time": 1254438881, // timestamp of the game start (Daily Chess only)
"time_control": "string", // PGN-compliant time control
"time_class": "string", // time-per-move grouping, used for ratings
"rules": "string", // game variant information (e.g., "chess960")
"eco": "string", //URL pointing to ECO opening (if available),
"tournament": "string", //URL pointing to tournament (if available)
}
],
"players": [
/** List of group's players */
{
"username": "username",
"points": 2, //points earned by player in this group adjuested in case of fair play recalculations)
"tie_break": 6, //tie-break points by player earned in this group
"is_advancing": false // {true, false}
}
]
}</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/TournamentRoundGroup.jsonld">https://api.chess.com/context/TournamentRoundGroup.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1/1">https://api.chess.com/pub/tournament/-33rd-chesscom-quick-knockouts-1401-1600/1/1</a></p>
<p><a id="pubapi-endpoint-matches" name="pubapi-endpoint-matches"></a></p>
<h6>Team matches</h6>
<p>All team matches-based URLs use the match "ID" to specify which match you want data for. <br /> <a href="https://api.chess.com/pub/match/">https://api.chess.com/pub/match/</a>{ID}</p>
<p>The <code>ID</code> is the same as found in the URL for the team match web page on <a href="http://www.chess.com">www.chess.com</a>. For example, the ID <a href="https://www.chess.com/club/matches/12803">WORLD LEAGUE Round 5: Romania vs USA Southwest</a> is <code>12803</code>.</p>
<p><a id="pubapi-endpoint-match-profile" name="pubapi-endpoint-match-profile"></a></p>
<h6>Team Match</h6>
<p><strong>Description:</strong> Get details about a team match and players playing that match. After the match is finished there will be a link to each player's stats endpoint, in order to get up-to-date information about the player. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/match/">https://api.chess.com/pub/match/</a>{ID} <br /> <strong>Data format of match in its registration phase:</strong></p>
<pre>{
"name": string,
"url": "URL", // the URL of the match on the website
"description": string, // description
"start_time" : timestamp, //manual or auto time start
"settings":{
"time_class": "daily", // only daily matches are supported for now
"time_control": string, // time control
"initial_setup": ,
"rules": string, // game variant information (e.g., "chess960")
"min_team_players": integer, //minimum number of players per team
"max_team_players": integer, //maximum number of players per team
"min_required_games": integer, //minimum number of required games
"min_rating": integer, //minimum rating of players to be admitted in this match
"max_rating": integer, //maximum rating of players to be admitted in this match
"autostart": boolean //if the match is set to automatically start
},
"status": "registration",
"boards": integer, // number of boards
"teams": {
"team1": {
"@id": "URL", // API URL for the club profile
"url": "URL", // Web URL for the club profile
"name": "string", // club name
"score": score, // Team score (adjuested in case of fair play recalculations)
"players": [
{
"username": "username",
"board": "url", // url of board
"rating": 1355, //rating of player
"rd": 25.12, //Glicko RD
"timeout_percent": 25.12, //timeout percentage in the last 90 days
"status": "basic" //status of user
}
]
},
"team2": {
"@id": "URL", // API URL for the club profile
"url": "URL", // Web URL for the club profile
"name": "string", // club name
"score": score, // Team score (adjuested in case of fair play recalculations)
"players": [
{
"username": "username",
"board": "url", // url of board
"rating": 1355, //rating of player
"timeout_percent": 25.21, //timeout percentage in the last 90 days
"status": "basic" //status of user
}
]
}
}
}</pre>
<p><br /> <strong>Data format in others phases of match (in progress, finished):</strong></p>
<pre>{
"name": string,
"url": "URL", // the URL of the match on the website
"description": string, // description
"start_time" : timestamp, //manual or auto time start
"settings":{
"time_class": "string", // time-per-move grouping, used for ratings
"time_control": string, // time control
"rules": string, // game variant information (e.g., "chess960")
"min_team_players":0, //minimum number of players per team
"max_team_players":0, //maximum number of players per team
"min_required_games":0, //minimum number of required games
"autostart":false
},
"status": string, // {finished, in_progress},
"boards": integer, // number of boards
"teams": {
"team1": {
"@id": "URL", // API URL for the club profile
"name": "string", // club name
"score": score, // Team score (adjuested in case of fair play recalculations)
"players": [
{
"username": "username",
"board": "url", // url of board
"stats": "url", //url to player's stats
"played_as_white": "string", //result {win, lose, resign, etc.} of player when played as white (if game's finished)
"played_as_black": "string" //result {win, lose, resign, etc.} of player when played as black (if game's finished)
}
],
"fair_play_removals":[
//list of usernames that were closed during match
]
},
"team2": {
"@id": "URL", // API URL for the club profile
"name": "string", // club name
"score": score, // Team score (adjuested in case of fair play recalculations)
"players": [
{
"username": "username",
"board": "url", // url of board
"stats": "url", //url to player's stats
"played_as_white": "string", //result {win, lose, resign, etc.} of player when played as white (if game's finished)
"played_as_black": "string" //result {win, lose, resign, etc.} of player when played as black (if game's finished)
}
],
"fair_play_removals":[
//list of usernames that were closed during match
]
}
}
}</pre>
<p><strong>Please note:</strong> we don't keep snapshots of user's statistics changes during matches, so after the registration phase you will able to get up-to-date statistics following the stats link of every player wich will lead to <a href="#pubapi-endpoint-player-stats"> Player's stats endpoint</a>.</p>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/Match.jsonld">https://api.chess.com/context/Match.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/match/12803">https://api.chess.com/pub/match/12803</a></p>
<p><a id="pubapi-endpoint-match-board" name="pubapi-endpoint-match-board"></a></p>
<h6>Team match board</h6>
<p><strong>Description:</strong> Get details about a team match board. Only in-progress or finished games will be included, so there may be one or two games in this list. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/match/">https://api.chess.com/pub/match/</a>{ID}/{board} <br /> <strong>Data format:</strong></p>
<pre>{
"board_scores":{
"player1": 0.5, // User score (adjuested in case of fair play recalculations)
"player2": 1.5 // User score (adjuested in case of fair play recalculations)
},
"games": [
{
"white": { // details of the white-piece player:
"username": "string", // the username
"rating": 1492, // the player's rating at the start of the game
"result": "string", // if game's finished, see "Game results codes" section
"@id": "string", // URL of this player's profile
"team": "url" // url to club's profile
},
"black": { // details of the black-piece player:
"username": "string", // the username
"rating": 1942, // the player's rating at the start of the game
"result": "string", // if game's finished, see "Game results codes" section
"@id": "string", // URL of this player's profile
"team": "url" // url to club's profile
},
"url": "string", // URL of this game
"fen": "string", // current FEN
"pgn": "string", // final PGN, if game's finished
"start_time": 1254438881, // timestamp of the game start (Daily Chess only)
"end_time": 1254670734, // timestamp of the game end, if game's finished
"time_control": "string", // PGN-compliant time control
"time_class": "string", // time-per-move grouping, used for ratings
"rules": "string", // game variant information (e.g., "chess960")
"eco": "string", //URL pointing to ECO opening (if available),
"match": "string", //URL pointing to team match (if available)
}
]
}</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/MatchBoard.jsonld">https://api.chess.com/context/MatchBoard.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/match/12803/1">https://api.chess.com/pub/match/12803/1</a></p>
<p><a id="pubapi-endpoint-country" name="pubapi-endpoint-country"></a></p>
<h6>Countries</h6>
<p>All country-based URLs use the country's 2-character ISO 3166 code (capitalized) to specify which country you want data for. <br /> <a href="https://api.chess.com/pub/country/">https://api.chess.com/pub/country/</a>{iso} <br /> <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2" target="_blank" rel="noopener">https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2</a></p>
<p>Chess.com supports players and clubs identifying with some regions that are not recognized countries in this ISO list. These countries are identified with codes within the "<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#User-assigned_code_elements">user-assigned code</a>" ranges. When possible, we tried to use codes that are commonly used in other applications. This is a list of these codes at Chess.com:</p>
<ul>
<li><code>XA</code> : "Canary Islands"</li>
<li><code>XB</code> : "Basque Country"</li>
<li><code>XC</code> : "Catalonia"</li>
<li><code>XE</code> : "England"</li>
<li><code>XG</code> : "Galicia"</li>
<li><code>XK</code> : "Kosovo"</li>
<li><code>XP</code> : "Palestine"</li>
<li><code>XS</code> : "Scotland"</li>
<li><code>XW</code> : "Wales"</li>
<li><code>XX</code> : "International"</li>
</ul>
<p>The presence or absence of any region on this list does not reflect any political opinion by Chess.com. We're just here to play chess. <img src="https://www.chess.com/bundles/web/images/icons/smileys/1x/happy.png" srcset="https://www.chess.com/bundles/web/images/icons/smileys/2x/happy.png 2x" title="happy" /></p>
<p><a id="pubapi-endpoint-country-profile" name="pubapi-endpoint-country-profile"></a></p>
<h6>Country Profile</h6>
<p><strong>Description:</strong> Get additional details about a country. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/country/">https://api.chess.com/pub/country/</a>{iso} <br /> <strong>Data format:</strong></p>
<pre>{
"@id": "URL", // the location of this profile (always self-referencing)
"name": "string", // the human-readable name of this country
"code": "string" // the ISO-3166-1 2-character code
}
</pre>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/Country.jsonld">https://api.chess.com/context/Country.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/country/IT">https://api.chess.com/pub/country/IT</a></p>
<p><a id="pubapi-endpoint-country-players" name="pubapi-endpoint-country-players"></a></p>
<h6>Country Players</h6>
<p><strong>Description:</strong> List of usernames for players who identify themselves as being in this country. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/country/">https://api.chess.com/pub/country/</a>{iso}/players</p>
<p><strong>Data Format:</strong></p>
<pre>{
"players": [
/* array of usernames for recently active players in this country */
]
}
</pre>
<p><strong>Note:</strong> complete lists of all players are not available to download. By requesting this list once per day, you will obtain a list of all new registrants and all people who are currently active on Chess.com and identify themselves as being in (or associated with) this country. People who switch their country designation will be included in the next generation of the list.</p>
<p><br /> <strong>Cache invalidation:</strong> This endpoints refresh at most once every 12 hours</p>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/CountryPlayers.jsonld">https://api.chess.com/context/CountryPlayers.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/country/IT/players">https://api.chess.com/pub/country/IT/players</a></p>
<p><a id="pubapi-endpoint-country-clubs" name="pubapi-endpoint-country-clubs"></a></p>
<h6>Country Clubs</h6>
<p><strong>Description:</strong> List of URLs for clubs identified as being in or associated with this country. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/country/">https://api.chess.com/pub/country/</a>{iso}/clubs</p>
<p><strong>Data Format:</strong></p>
<pre>{
"clubs": [
/* array of profile URLs for clubs in this country */
]
}
</pre>
<p><strong>Note:</strong> the "country" of a club means different things to different clubs. In some cases, the clubs solicit membership from people in that country; in others, they attempt to meet for OTB chess and the country is where they do that; sometimes it indicates the language spoken; sometimes it's just the country of the founder and they haven't given it much thought.</p>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/CountryClubs.jsonld">https://api.chess.com/context/CountryClubs.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/country/IT/clubs">https://api.chess.com/pub/country/IT/clubs</a></p>
<p><a id="pubapi-daily-puzzle" name="pubapi-daily-puzzle"></a></p>
<h6>Daily puzzle</h6>
<p><strong>Description:</strong> Information about the daily puzzle found in <a href="http://www.chess.com">www.chess.com</a> . <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/puzzle">https://api.chess.com/pub/puzzle</a></p>
<p><strong>Data Format:</strong></p>
<pre>{
"title": "title", //the title of the daily puzzle
"url": "URL", //url to daily puzzle in chess.com
"publish_time": 1513584000, //the date of the published puzzle
"fen": "FEN", //the FEN of the published puzzle
"pgn": "PGN", //the PGN of the published puzzle, and yes, we know that thing you have noticed ;)
"image":"the link to the image"
}
</pre>
<p><strong>Note:</strong> if you are going to publish the Daily Puzzle somewhere please remember to give credits to Chess.com by means of a clearly visibile text link that points to the url of the puzzle page.</p>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/DailyPuzzle.jsonld">https://api.chess.com/context/DailyPuzzle.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/puzzle">https://api.chess.com/pub/puzzle</a></p>
<p><a id="pubapi-random-daily-puzzle" name="pubapi-random-daily-puzzle"></a></p>
<h6>Random daily puzzle</h6>
<p><strong>Description:</strong> Information about a randomly picked daily puzzle. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/puzzle/random">https://api.chess.com/pub/puzzle/random</a></p>
<p><strong>Data Format:</strong></p>
<pre>{
"title": "title", //the title of the daily puzzle
"url": "URL", //url to daily puzzle in chess.com
"publish_time": 1513584000, //the date of the published puzzle
"fen": "FEN", //the FEN of the published puzzle
"pgn": "PGN", //the PGN of the published puzzle, and yes, we know that thing you have noticed ;)
"image":"the link to the image"
}
</pre>
<p><strong>Notes:</strong> the puzzle doesn't change every request but has some caching latency (around 15 seconds). If you are going to publish the Daily Puzzle somewhere please remember to give credits to Chess.com by means of a clearly visibile text link that points to the url of the puzzle page.</p>
<p><strong>JSON-LD Context:</strong> <a href="https://api.chess.com/context/DailyPuzzle.jsonld">https://api.chess.com/context/DailyPuzzle.jsonld</a> <br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/puzzle/random">https://api.chess.com/pub/puzzle/random</a></p>
<p><a id="pubapi-streamers" name="pubapi-streamers"></a></p>
<h6>Streamers</h6>
<p><strong>Description:</strong> Information about Chess.com streamers. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/streamers">https://api.chess.com/pub/streamers</a></p>
<p><strong>Data Format:</strong></p>
<pre>{
"streamers":[
{
"username": "string",
"avatar": "URL",
"twitch_url": "Twitch.tv URL",
"url":"member url's"
}
]
}
</pre>
<p><strong>Notes:</strong> the endpoint refreshes every 5 minutes.</p>
<br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/streamers">https://api.chess.com/pub/streamers</a></p>
<p><a id="pubapi-leaderboards" name="pubapi-leaderboards"></a></p>
<h6>Leaderboards</h6>
<p><strong>Description:</strong> It displays information about top 50 player for daily and live games, tactics and lessons. <br /> <strong>URL pattern:</strong> <a href="https://api.chess.com/pub/leaderboards">https://api.chess.com/pub/leaderboards</a></p>
<p><strong>Data Format:</strong></p>
<pre>
{
"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" /* [1..50] */
},
[...]
],
"live_rapid":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_blitz":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_bullet":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_bughouse":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_blitz960":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_threecheck":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_crazyhouse":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"live_kingofthehill":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"lessons":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
],
"tactics":[
{
"player_id": "integer",
"@id": "URL",
"url": "URL",
"username": "string",
"score": "integer",
"rank": "integer" /* [1..50] */
},
[...]
]
}
</pre>
<p><strong>Notes:</strong> the endpoint refreshes when one of the leaderboards is updated.</p>
<br /> <strong>Example:</strong> <a href="https://api.chess.com/pub/leaderboards">https://api.chess.com/pub/leaderboards</a></p>
<p><a id="game-results" name="game-results"></a></p>
<hr />
<h3>Game results codes</h3>
<p>In the table below are listed all codes that are returned by game related endpoints.</p>
<table border="1">
<tbody>
<tr>
<th>Code</th>
<th>Description</th>
</tr>
<tr>
<td>win</td>
<td>Win</td>
</tr>
<tr>
<td>checkmated</td>
<td>Checkmated</td>
</tr>
<tr>
<td>agreed</td>
<td>Draw agreed</td>
</tr>
<tr>
<td>repetition</td>
<td>Draw by repetition</td>
</tr>
<tr>
<td>timeout</td>
<td>Timeout</td>
</tr>
<tr>
<td>resigned</td>
<td>Resigned</td>
</tr>
<tr>
<td>stalemate</td>
<td>Stalemate</td>
</tr>
<tr>
<td>lose</td>
<td>Lose</td>
</tr>
<tr>
<td>insufficient</td>
<td>Insufficient material</td>
</tr>
<tr>
<td>50move</td>
<td>Draw by 50-move rule</td>
</tr>
<tr>
<td>abandoned</td>
<td>Abandoned</td>
</tr>
<tr>
<td>kingofthehill</td>
<td>Opponent king reached the hill</td>
</tr>
<tr>
<td>threecheck</td>
<td>Checked for the 3rd time</td>
</tr>
<tr>
<td>timevsinsufficient</td>
<td>Draw by timeout vs insufficient material</td>
</tr>
<tr>
<td>bughousepartnerlose</td>
<td>Bughouse partner lost</td>
</tr>
</tbody>
</table>
<p><a id="pubapi-roadmap" name="pubapi-roadmap"></a></p>
<hr />
<h3>Roadmap</h3>
<p>Features in progress:</p>
<ul>
<li>Revision of JSON-LD policies</li>
<li>Exploring options for historic ratings lists</li>
<li>Better error and rate-limiting handling</li>
</ul>
<p>Please contribute bug reports, comments, and feature requests in the forums!</p>
<hr />
<ul style="font-size: 10pt;">
<li>Last reviewed and updated: 2019-06-11</li>
<li>Comments: <a href="https://www.chess.com/news/view/published-data-api#comments">https://www.chess.com/news/view/published-data-api#comments</a></li>
<li>Revisions: <a href="https://gist.github.com/andreij/0e3309200c0a6bb26308817a168203f3/revisions" target="_blank" rel="noopener">https://gist.github.com/andreij/0e3309200c0a6bb26308817a168203f3/revisions</a></li>
</ul>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment