Forums

[GUIDE] Unofficial API documentation

Sort:
Eyal282

The creation of this guide may lead to blockades within the unofficial API, as it is not known if one or more pieces of data this guide contains may be purposely hidden by Chess.com for legal or their own reasons. However I hope this guide will not have a capacity to be used abusively.

Let's start with a link to the official API documentation

https://www.chess.com/news/view/published-data-api

If you're still here you want undocumented stuff. Let me warn what it means to use undocumented endpoints:

List of endpoints that don't exist:
1. About Me in a player's profile


I will send links and mention what useful stuff I found in them. In all of them, the website will look like this, with {username} replaced by hikaru, for hikaru's account: https://www.chess.com/callback/user/popup/{username}

 

Let's start:

https://www.chess.com/callback/user/popup/hikaru

This is generated from trying to message hikaru, and answers the following questions?
What's your status*? Are you a staff? What type of premium do you have? Can I gift you a premium subscription, and why? what's your Country ID? Are we friends? Did I send you a friend request? Did you send me a friend request? What's your top puzzle rush score? What's your best rating? In what time control your best rating is?

* Status is not Biography of the user, it's the 50 character status as you input directly in your profile page.

 

I will be honest. I don't have anything else, so I will let you know how to get the PGN of a game by its URL

 

Step 1: Take a random URL you need. I will use this: https://www.chess.com/game/live/15360860817

 

Step 2: Go to this endpoint, the number being the ID of the game. Notice live and game are swapped for unknown reasons: https://www.chess.com/callback/live/game/15360860817

Step 3: From the unofficial endpoint of the callback fetch the date of the game.

Step 4: Use the official API to fetch all games within the same month of one of the participants ( top or bottom )

Step 5: Find the URL of the game within the result, as the URL itself is given.

Step 6: You also get a PGN.

Step 7: ????

Profit

 

 

 

https://www.chess.com/callback/member/activity/hikaru?page=1

 

This endpoint allows you to see hikaru's recent activity over Chess.com

Let me know if you have other uses which you know the way to do / want to know how to do.

https://www.chess.com/callback/user/games?locale=en_US&all=1&userId=15448422

This gets Hikaru's last games, which is extremely useful for some deep learning programs. The User ID of hikaru was found here, which is identical to one of the other callbacks in this guide:

https://www.chess.com/callback/user/popup/hikaru

 

 

 

https://www.chess.com/callback/live/stats/hikaru/chart?daysAgo=30&type=blitz

 

This one finds a chart of Hikaru's changes in blitz. You can change time control and days to pinpoint data.

 

https://www.chess.com/callback/member/stats/hikaru

 

General stats of Hikaru from the unofficial API of Chess.com. It gives an important missing data of latest tactics rating.

 

https://www.chess.com/callback/leagues/user-league/search/hikaru

 

League stats of Hikaru from the unofficial API of Chess.com

Martin_Stahl

Using functionality that isn't part of the official APIs may fall afoul of the site TOS.

YankeeBastid

I need to retrieve a player's current rank. Then when they play a match, the new rank that is awarded plus date-timestamp. I need the type of match, I am shooting for the 30-minute matches. I am developing 4teamchess.com, a daily tournament that allows novice players the chance to be teamed with advanced and two intermediate players from all over the world. I have Erik's ok on this.

Eyal282
Martin_Stahl wrote:

Using functionality that isn't part of the official APIs may fall afoul of the site TOS.

I will check this out, and delete if needed. 

Edit: I will be serious, I have no clue. I will report my own thread so if it does violate something, it is more visible to you

 

Edit: I cannot find a report button

Eyal282
YankeeBastid wrote:

I need to retrieve a player's current rank. Then when they play a match, the new rank that is awarded plus date-timestamp. I need the type of match, I am shooting for the 30-minute matches. I am developing 4teamchess.com, a daily tournament that allows novice players the chance to be teamed with advanced and two intermediate players from all over the world. I have Erik's ok on this.

What is a rank?

 

Edit: Couldn't figure it out, but I can make a special request to fetch my own, maybe it can lead you to the right direction: https://www.chess.com/callback/leaderboard/live/sidebar/blitz/stats

YankeeBastid

Your rating. Mine is 823 in 30 minute matches

YankeeBastid

That retrieves every member and their rating. I need to retrieve a specific rating for a player when requested.

Eyal282
YankeeBastid wrote:

Your rating. Mine is 823 in 30 minute matches

Isn't this reported in the official API? 30 minute matches are treated as Rapid by Chess.com

Eyal282
Martin_Stahl wrote:

Using functionality that isn't part of the official APIs may fall afoul of the site TOS.

I will continue doing this as I am clearly following a Chess.com goal, all while not finding a fault in ToS. If this is deleted I will of course stop:

ChessGrandmaster2600

credit would be cool seeing as i introduced this to you lol 

also this thread brings a ton of attention and they might add restrictions to it to prevent abuse

Martin_Stahl
Eyal282 wrote:
Martin_Stahl wrote:

Using functionality that isn't part of the official APIs may fall afoul of the site TOS.

I will continue doing this as I am clearly following a Chess.com goal, all while not finding a fault in ToS. If this is deleted I will of course stop:

 

I said may. If something is not part of the API it may violate the following from the TOS:

Member Conduct

You agree to not use the Service to:

  • use any robot, spider, site search/retrieval application, or other manual or automatic device or process to retrieve, index, “data mine,” or in any way reproduce or circumvent the navigational structure or presentation of the Service or its contents;

 

https://www.chess.com/legal/user-agreement

Eyal282
Martin_Stahl wrote:
Eyal282 wrote:
Martin_Stahl wrote:

Using functionality that isn't part of the official APIs may fall afoul of the site TOS.

I will continue doing this as I am clearly following a Chess.com goal, all while not finding a fault in ToS. If this is deleted I will of course stop:

 

I said may. If something is not part of the API it may violate the following from the TOS:

Member Conduct

You agree to not use the Service to:

  • use any robot, spider, site search/retrieval application, or other manual or automatic device or process to retrieve, index, “data mine,” or in any way reproduce or circumvent the navigational structure or presentation of the Service or its contents;

 

https://www.chess.com/legal/user-agreement

That's really hard to pinpoint if I'm doing it. Please let me know if I'm doing something wrong. I had no bad intentions in mind when creating this guide or circumventing the official API, it's just missing stuff and chess.com clearly wants to send all of the website's data as an API but I guess they're slightly busy.

MGleason

If there is something that is an actual endpoint provided by the site (as opposed to scraping the HTML), I wouldn't see it as a violation of the TOS.  I would see it as using an undocumented feature that is subject to change without warning, which could therefore break any project that relies on it.

A strict interpretation of the TOS would actually probably prohibit even the use of the documented API, which is clearly not the intent.

Coach_Cecil

This lists my club's little leaderboard:

https://www.chess.com/leaderboard/live/rapid?group=54071

Unfortunately it omits inactive players which is all well and good for the site but I need them included for the internal shenanigans of the club. Please help.

Eyal282
Coach_Cecil wrote:

This lists my club's little leaderboard:

https://www.chess.com/leaderboard/live/rapid?group=54071

Unfortunately it omits inactive players which is all well and good for the site but I need them included for the internal shenanigans of the club. Please help.

https://www.chess.com/clubs/members/grassy-park-chess-academy

I would imagine the API would be here, but I cannot trace an API to lead to that result.

 

Edit: https://api.chess.com/pub/club/grassy-park-chess-academy/members

ronyfreitas

Can you tell me if I can get statistics from this endpoint passing parameters such as the year?

MGleason

With undocumented stuff, usually trial and error is the only way to obtain information.