Chess.com Published-Data API

pubapi_docs.html

<ul style="font-size: 10pt">
    <li>Last reviewed and updated: 2017-11-05</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/BiviaBen/87bd7f830b6f1a8ba6b537f4e0c87e95/revisions">https://gist.github.com/BiviaBen/87bd7f830b6f1a8ba6b537f4e0c87e95/revisions</a></li>
</ul>

<hr>
<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>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-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>Team Matches <em>(in progress)</em></li>
              <li>Tournaments <em>(in progress)</em></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>Team Matches <em>(in progress)</em></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>
    </ul>
  </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 data 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><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-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><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> https://api.chess.com/pub/player/{username}
<br>
<strong>Data format:</strong></p>
<pre>
{
  "@id": "URL", // the location of this profile (always self-referencing)
  "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, 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
}
</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> https://api.chess.com/pub/titled/{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.
<br>
<strong>URL pattern:</strong> https://api.chess.com/pub/player/{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 */
  }
}
</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.</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 // integer percentage of games lost by timeout
  },
  "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-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> https://api.chess.com/pub/player/{username}/games</p>

<p><strong>Data Format, each Game:</strong></p>
<pre>
{
  "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")
}
</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> https://api.chess.com/pub/player/{username}/games/to-move</p>

<p><strong>Data Format, each Game:</strong></p>
<pre>
{
  "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> https://api.chess.com/pub/player/{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> https://api.chess.com/pub/player/{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", // the player's result
    "@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", // the player's result
    "@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
  "time_class": "string", // time-per-move grouping, used for ratings
  "rules": "string" // game variant information (e.g., "chess960")
}
</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> https://api.chess.com/pub/player/{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.
<br>
<strong>URL pattern:</strong> https://api.chess.com/pub/player/{username}/clubs</p>

<p><strong>Data Format:</strong></p>
<pre>
{
  "clubs": [
    /* array of URLs for club profiles */
  ]
}
</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-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>
https://api.chess.com/pub/club/{url-ID}</p>

<p>The <code>url-ID</code> is the same as found in the URL for the club's web page on www.chess.com. 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> https://api.chess.com/pub/club/{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
  "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-member usernames, grouped by club-activity frequency.
<br>
<strong>URL pattern:</strong> https://api.chess.com/pub/club/{url-ID}/members</p>

<p><strong>Data Format:</strong></p>
<pre>
{
  "weekly": [
    /* array of usernames for members active in the club this week */
  ],
  "monthly": [
    /* array of usernames for members active in the club this month */
  ],
  "all_time": [
    /* array of usernames for all other members of this club */
  ]
}
</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> <em>in progress</em></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-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>
https://api.chess.com/pub/country/{iso}
<br>
<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">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> https://api.chess.com/pub/country/{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> https://api.chess.com/pub/country/{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> these lists are only updated at most once per day, and only include players who have logged in since midnight the day before. 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><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> https://api.chess.com/pub/country/{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-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>
    <li>Improved caching for faster responses</li>
</ul>

<p>Endpoints in progress:</p>

<ul>
    <li>Clubs (current matches, archived matches, stats)</li>
    <li>Tournaments (summary, results, player links)</li>
    <li>Team Matches (summary, results, club links, player links)</li>
    <li>Games: adding tournament and team match info</li>
</ul>

<p>Please contribute bug reports, comments, and feature requests in the forums!</p>