Skip to main content
All CollectionsCommunity
Published-Data API
Published-Data API
Updated over a month ago

API

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.

💡 If you need tips on using the API, feel free to ask in the Developer Community Club forums!

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 curl for more detailed information. For example, curl -v https://api.chess.com/pub/player/hikaru returns 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

  • JSON-LD: Data is provided in JSON-LD format, compatible with regular JSON. We include a Link header for context.

  • JSONP: Supports callback parameters for function calls in a script tag.

📝 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: gzip header, 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 request.

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

  1. Determine the data you need and construct the URL based on the endpoint URL pattern.

  2. Request the URL using your browser, program, Postman, cURL, or any other tool.

  3. 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

Did this answer your question?