What is the PubAPI and how do I use it?

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!

Chess.com brand and intellectual property

Our APIs and documentation are public, and we want the chess ecosystem to thrive. At the same time, we do require that you respect our IP: chessboard color palettes, piece designs, sound effects, move classification glyphs, feature names ('Game Review', etc), UI/UX/design, and any other features recognized as Chess.com products. You may use our API as long as you do not abuse/spam our users, disrupt/harm our service, or copy our features or IP.

Chess.com’s approach to third-party extensions:

We appreciate that developers build tools and extensions that make Chess.com even better for players. To help keep the platform fair, secure, and fun for everyone, here’s how we approach these extensions.

Respect our brand and IP. You're welcome to build non-commercial independent tools that don't directly compete with Chess.com and/or it's products, including ones offering functionality similar to a Chess.com feature (like your own analysis or training tool), using our public data. We just ask that you don't use Chess.com's name for your tool (e.g., calling it 'Game Review'), copy our UI or designs, or otherwise use Chess.com's branding, terminology, or other copyrighted material. Your tool should be clearly differentiated from Chess.com's own products in look, feel, and naming.
Keep the game fair. Extensions shouldn’t provide engine analysis, move suggestions, automation, or anything else that could violate our Fair Play Policy, regardless of what else the extension does.
Access data the right way. Extensions are welcome to use our published, documented APIs (subject to the API’s own terms of use). Extensions may not do scraping, access undocumented endpoints, or other backend workarounds outside of normal page rendering and permitted API use.
Are non-commercial. We’re supportive of free, community-built extensions. If a developer wants to sell the extension, sell in-extension items, or build a companion marketplace tied to Chess.com, we’re open to proposals, just reach out to our Business Development team to discuss.
Are clear about the relationship. Extensions shouldn’t use our name, logo, or marks in a way that suggests official partnership, endorsement, or affiliation. That said, something like “Compatible with Chess.com” is totally fine, as long as it’s clear the extension isn’t affiliated with or endorsed by us.

Please remember, this is a general policy to provide helpful guidelines for when we are okay with Third-party extensions, not an official endorsement, partnership, or sponsorship of any specific extension. We also reserve the right to update this approach, or make exceptions for individual extensions, at any time as things evolve. If you are not sure, please ask us!

If you are interested in building an app or service for members of Chess.com and would like to authenticate users, access public user data, or set up a connected board, please fill out this form, and we will get back to you with instructions.

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

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 to learn more about our API and get the endpoints you may need: Published-Data API