If you need tips on using the API, feel free to ask in the Developer Community Club forums!
The PubAPI is a read-only REST API that provides JSON-LD data. It repackages all publicly available data from our website, such as player data, game data, and club/tournament information. It does not include private information like game chat or conditional moves, which are restricted to logged-in users.
The PubAPI is read-only. You cannot send game moves or other commands to Chess.com through this system.
General use features and issues
Before starting, please review the following common features and issues:
Feature | Issue |
Cache Invalidation | Endpoints refresh at most once every 12 hours. |
Rate Limiting | Serial access is unlimited. Parallel requests may trigger rate limiting, resulting in a "429 Too Many Requests" response. |
Abnormal activity may result in temporary blocking. Including a user-agent with contact info can help resolve this. A user-agent string is an HTTP header. The programming tool you're using should allow you to add headers to your request. Add something like:
User-Agent: my-profile-tool/1.2 (username: your_username; contact: me@example.com)
How to get PubAPI data
Using a Browser: Simply enter the endpoint URL (e.g., https://api.chess.com/pub/player/hikaru) in your browser’s address bar.
Command Line: Use
curlfor more detailed information. For example,curl -v https://api.chess.com/pub/player/hikarureturns response codes, Etag, date, and last-modified headers.Online Tools: Tools like JSON Formatter can render responses in a readable format.
Postman/Insomnia: Use these tools for a user-friendly interface. Download our collection of endpoints. Follow instructions to import collections for Postman or Insomnia.
JSON-LD and JSONP
JSONP function names containing non-literal chars or longer than 200 chars will be removed from response.
Caching
Each response includes ETag and Last-Modified headers. If your client includes the If-None-Match and If-Modified-Since headers in the request, and the data has not changed since your last request, you will receive a 304 Not Modified response code, indicating it is safe to use your cached version.
If you request data more frequently than the Cache-Control header's max-age value, our CDN may provide cached values. For requests beyond the max-age interval, the CDN will verify the data's currency before responding. You may see headers indicating a cache HIT, MISS, EXPIRED, or REVALIDATED.
HTTP Compression and HTTP/2
Compression: If the request includes an
Accept-Encoding: gzipheader, the response will be gzip compressed when it is beneficial - typically for data larger than 200 bytes. This can reduce download bandwidth by up to 80%HTTP/2: Supports header compression, binary transfer, and multiplexed responses.
Response codes
Response codes are used to tell your client about the state of the data you requests.
Code | Meaning |
200 | Successful request |
301 | Redirected to a new URL |
304 | Data not modified since the last request |
404 | URL malformed or data not available |
410 | Data permanently unavailable |
429 | Rate limit exceeded |
How to use the PubAPI
Determine the data you need and construct the URL based on the endpoint URL pattern.
Request the URL using your browser, program, Postman, cURL, or any other tool.
Enjoy the JSON data!
Check out this article on the main site to learn more about our API and get the endpoints you may need: Published-Data API