Forum

This is something I've been mulling for a while. It's clearly not critical, but with the enhancement request for clubs by club_id and players by player_id, I'll send in the enhancement request and worst is I hear "No." Or "Well, probably not and we think it's low priority." Now and then someone provides a URL for one or more games. To get the PGN for that game or games, go to the website, select download and then in the pop-up select and copy or download according to preference. It would be "hands free" to download a game by ID/UUID. My first choice I think would be to get the full JSON for the game (programatically it's easy enough to ignore everything but the PGN if that is all that is wanted) and second choice to receive only the PGN.

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-board The team match board endpoint is documented to contain a "team" element for each player in each game with its value being the url of the team the player played or is playing for in the match. 1. It's unclear if I should expect https://api.chess.com/. or https://www.chess.com/.. 2. Whatever I should expect, I'm not getting the "team" element at all. (Workaround: use the list of players from the team match endpoint, which I already have, instead of comparing on team @id or url, both of which I also have.) Documentation: https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-board { "board_scores":{ ... }, "games": [ { "white": { // details of the white-piece player: ... "team": "url" // url to club's profile },...} Example output: https://api.chess.com/pub/match/893502/1 {"board_scores":{"lrj2011":2,"impractical":0},"games":[{"url":"https://www.chess.com/daily/game/194799652","pgn":"[Event \"TMCL 2018 A1 R5 - Board 1\"]\n[Site \"Chess.com\"]\n[Date \"2018.05.15\"]\n[Round \"-\"]\n[White \"lrj2011\"]\n[Black \"Impractical\"]\n[Result \"1-0\"]\n[ECO \"B75\"]\n[ECOUrl \"https://www.chess.com/openings/B75-Sicilian-Defense-Open-Dragon-Yugoslav-Attack-7...a6\"]\n[WhiteElo \"2348\"]\n[BlackElo \"2275\"]\n[TimeControl \"1/259200\"]\n[Termination \"lrj2011 won by resignation\"]\n[StartTime \"16:05:28\"]\n[EndDate \"2018.07.10\"]\n[EndTime \"12:18:10\"]\n[Link \"https://www.chess.com/daily/game/194799652\"]\n\n1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 g6 6. Be3 Bg7 7. f3 a6 8. Qd2 Nbd7 9. O-O-O b5 10. g4 Bb7 11. h4 Nb6 12. h5 Rg8 13. hxg6 hxg6 14. g5 Nfd7 15. a3 Ne5 16. f4 Nec4 17. Qe1 Qc7 18. Bf2 Rc8 19. Rh3 d5 20. e5 e6 21. Na2 Bf8 22. Bxc4 dxc4 23. Nc3 b4 24. axb4 Bd5 25. b5 Ra8 26. Qg1 Nd7 27. Nxd5 exd5 28. Qg2 Qb7 29. Nc6 axb5 30. Qxd5 Ra1+ 31. Kd2 1-0","time_control":"1/259200","end_time":1531225090,"rated":true,"fen":"4kbr1/1q1n1p2/2N3p1/1p1QP1P1/2p2P2/7R/1PPK1B2/r2R4 b - - 2 31","start_time":1526400328,"time_class":"daily","rules":"chess","white":{"rating":2439,"result":"win","@id":"https://api.chess.com/pub/player/lrj2011","username":"lrj2011"},"black":{"rating":2324,"result":"resigned","@id":"https://api.chess.com/pub/player/impractical","username":"Impractical"},"eco":"https://www.chess.com/openings/B75-Sicilian-Defense-Open-Dragon-Yugoslav-Attack-7...a6","match":"https://api.chess.com/pub/match/893502"},{"url":"https://www.chess.com/daily/game/194799650","pgn":"[Event \"TMCL 2018 A1 R5 - Board 1\"]\n[Site \"Chess.com\"]\n[Date \"2018.05.15\"]\n[Round \"-\"]\n[White \"Impractical\"]\n[Black \"lrj2011\"]\n[Result \"0-1\"]\n[ECO \"A45\"]\n[ECOUrl \"https://www.chess.com/openings/A45-Indian-Game\"]\n[WhiteElo \"2275\"]\n[BlackElo \"2348\"]\n[TimeControl \"1/259200\"]\n[Termination \"lrj2011 won by resignation\"]\n[StartTime \"16:05:28\"]\n[EndDate \"2018.07.26\"]\n[EndTime \"11:02:16\"]\n[Link \"https://www.chess.com/daily/game/194799650\"]\n\n1. d4 Nf6 2. Bf4 g6 3. Nf3 Bg7 4. e3 O-O 5. Nc3 d5 6. Be2 c5 7. dxc5 Qa5 8. Nd2 Qxc5 9. Nb3 Qb6 10. Nb5 Ne8 11. c3 e5 12. Bg3 Be6 13. a4 a6 14. a5 Qd8 15. Na3 Nc6 16. Nc5 Nd6 17. b4 h5 18. h3 Nf5 19. Bh2 Qg5 20. g4 hxg4 21. hxg4 Nd6 22. Qc2 Bxg4 23. Rg1 Qh5 24. Bxg4 Qxh2 25. O-O-O e4 26. Nd7 Ne5 27. Rh1 Nd3+ 28. Kb1 Qxf2 29. Nxf8 Kxf8 30. Be2 Qxe3 31. Bxd3 exd3 32. Rxd3 Qe7 33. Rxd5 Ne4 34. Rd3 Rc8 35. Rhh3 Nxc3+ 36. Rxc3 Bxc3 0-1","time_control":"1/259200","end_time":1532602936,"rated":true,"fen":"2r2k2/1p2qp2/p5p1/P7/1P6/N1b4R/2Q5/1K6 w - - 0 37","start_time":1526400328,"time_class":"daily","rules":"chess","white":{"rating":2283,"result":"resigned","@id":"https://api.chess.com/pub/player/impractical","username":"Impractical"},"black":{"rating":2445,"result":"win","@id":"https://api.chess.com/pub/player/lrj2011","username":"lrj2011"},"eco":"https://www.chess.com/openings/A45-Indian-Game","match":"https://api.chess.com/pub/match/893502"}]}

This one's a bit tricky; I can imagine it may need a change to backend database storage. It's useful enough to me and I imagine to future chess.com internal use that I'm going to ask for it anyway. The player profile endpoint: https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player ... has: "joined": 1178556600, // timestamp of registration on Chess.com I would like to see: "closed": 1188556600, // timestamp of account closure on Chess.com The advantage to me is that when calculating results for incomplete matches that have passed a deadline, I can tell when they were closed and not have to guess based on last_online time ... since people do sleep. A self-closure time and last_online time should be close. An abuse or fair_play_violations closure may not be. For chess.com, it provides a timestamp after which no moves can have been played; if desired in progress games can be timed out immediately and there is a record of when someone left, and if staff access an account (which seems to upset last_online time) there remains a record of when the account owner last accessed the account. In he case an account is reopened (which I have seen for self-closures, closures for abuse and fair play violations closures) the "closed" timestamp should be deleted and no longer provided. A potential problem exists were account profiles and/or stats are cached with the account considered closed, but the addition of a "closed" timestamp doesn't worsen that case. My particular impetus for wishing to know when a particular account was closed was for TMCL: one user's account was closed about the TMCL deadline. The last_online time preceded the deadline, but the exact time of closure is a mystery. Thanks for your consideration, Giles

I'm currently involved in collating the results of the first RR in the TMCL 2018 tournament. The match endpoint API requests I've been making have gone without a hitch & I'm impressed at just how robust that system is. At present I'm not even bothering to trap errors relating to my API server requests & there hasn't been a single failure (out of several hundred), so kudos to the developers! But I've hit a very small snag regarding the team name for the matches of just one of the groups taking part & it's this one:- World's Best Chess Players - Лучшие Шахматисты в мире I'm finding that the string I'm using, copied directly from the group's home page, doesn't correspond to the match endpoint name which is as follows:- World's Best Chess Players - \u041b\u0443\u0447\u0448\u0438\u0435 \u0428\u0430\u0445\u043c\u0430\u0442\u0438\u0441\u0442\u044b \u0432 \u043c\u0438\u0440\u0435 I recognise the (Russian cyrilic?) unicode character codes used to represent the cyrilic part of the name but I don't understand why this should be giving me a problem. We have a host of teams with names that contain non Latin characters & they're all fine. Another puzzle is this - when I do a comparison between the two strings using the command line of my Python (V3) interpreter like this... "World's Best Chess Players - Лучшие Шахматисты в мире" == "World's Best Chess Players - \u041b\u0443\u0447\u0448\u0438\u0435 \u0428\u0430\u0445\u043c\u0430\u0442\u0438\u0441\u0442\u044b \u0432 \u043c\u0438\u0440\u0435" ..the result is True. It's odd because my Python script is left treating the two names as if they're not the same but it appears to recognise them as the same on the command line, so what's going on? * This team name involves the same process as the one above but cause no problems.. Захід From a typical match endpoint for that group: "name":"\u0417\u0430\u0445\u0456\u0434"

Hi, In discussing a report with some other admins, it's come up that it would sometimes be useful to know when someone last played a team match. The stats endpoint gives "last" for chess_daily, chess960_daily, chess_blitz etc with timestamp, rating and Glicko RD. That's all good. I am unsure how much I want this (probably less than I want, say, a vote chess endpoint) and definitely less than a bug or two out there (rating inconsistency on team boards vs the website, if I remember right) but I'll throw it out. If other people want it, please chime in. If it would be difficult to do or slow, "Thanks, but no thanks" might be the right answer. The workaround for anyone who really needs this is to get the player's archive and work back through the games. That won't give the Glicko RD at the time of the most recent tournament game or whatever, but it would provide everything else. Thanks, Giles

I created a Java library that has useful methods that convert JSON data provided by the chess.com API endpoints into basic Java objects like Integers and Strings. This may prove useful to anyone that wanted to do something with the API data but wants to skip the whole JSON processing mess. For example, you can get a user´s rating in just one line of code with the library: int rating = UserJs.getBlitz("Nichtgut"); https://github.com/AntonioBohne/Chess.comJSON-JavaAPI You can download all the necessary files from there. Hopefully this helps someone (that isn´t me lol).

Hi guys, I would like to call the last 10 games from my archive, do you have an example of code to do this?

I created a String Array with all the users under the "all_time" JSON array. Chess.com says this club has 991 members. The string array only has 753 usernames. Just to doublecheck I manually copied everything after "all_time" and pasted it here: https://wordcounttools.com/ It also shows the word count for "username" is 753. Who is wrong?

I want to play around with JSON. I want to retrieve basic information about a club like getting a list of the members' countries, members' rating etc... Simple stuff that can be accesed trough the API. Just wondering if anyone has done this already, I dont want to reinvent the wheel...

Hi, The documentation at: https://www.chess.com/news/view/published-data-api#pubapi-endpoint-games-archive-list implies that live games should be returned by the following (or any similar) URL: https://api.chess.com/pub/player/djcaf/games/2011/11/pgn This does not seem to be the case. Unless I am missing somthing the following live game should be returned but does not seem to be; https://www.chess.com/live/game/202420638 Any ideas? Thanks

Hi, I'm using the per-board team match URL: https://api.chess.com/pub/match/876452/13 That's a tricky example, as both players were closed for fair play violations. The returned data begins: {"board_scores":{"nmarvel":1,"bishop_ate":1}, ... That's all well and good, but: 1. The match from which this example comes is Oracle "team1" vs Canichess Alumni "team2" but the order has been reversed, as @bishop_ate was playing for Oracle and @nmarvel for Canichess Alumni (and <your favourite programming language>'s JSON support might or might not preserve order anyway) 2. If the two teams both clean out closed accounts then a lookup of their current team members will find neither name [Edit: closed accounts don't show in team member lists via api.chess.com, so this point is moot. ] 3. The solution should be to ignore "board_result" and look at the individual games, each of which is specified to include a "team" url for each player so that I know who belonged (or maybe belongs, but I don't want to care about "now", I care about when the match was started) just as the documentation says: https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-board "games": [ { "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", // if game's finished, see "Game results codes" section "@id": "string", // URL of this player's profile "team": "url" // url to club's profile },... Unfortunately, I'm not seeing the "team" included: ..."white":{"rating":1919,"result":"timeout","@id":"https://api.chess.com/pub/player/nmarvel","username":"NMarvel"},... I can't tell about Canichess Alumni and @NMarvel, but I am an admin in Oracle and it appears that @Bishop_ate has been purged from the list of closed accounts. Now I'm kinda stuck: the website can tell who played for which team, provide links to the games with the actual result, show the chess.com adjusted result in the match page ... but some of that data I don't see how to get to. Background (may/may not help): I am writing a script to score TMCL matches. TMCL has a cutoff date; before that date all results are provisional, and while it will rarely if ever make a difference I want to match the 2018 rules which give 0:0 when both accounts are closed due to fair play violations, so that my script matches people's manual checks, and believe me, some people will check! There's also the fact that 0:0 might not be exactly the same as 1/2-1/2 when tie-breaks come into the picture, but that's not my problem today.

Documentation at https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-board is quite specific: "rating": 1492, // the player's rating at the start of the game ... I would like to use the player ELO rating at the start of a match (with other factors) to try to forecast potential outcomes (e.g. multiple regression). Currently ratings associated with match boards are changing through the game. It is the starting player ELO at the time the match starts, but then the API returns the rating that is current at the time of the request. When the game finishes, the rating that is kept is the rating of the players at the end of the game. After exchanging ideas with @skelos (he has reported this as documentation mismatch at https://www.chess.com/clubs/forum/view/in-progress-match-board-has-diverged-from-the-documentation), but this seems to be a bug as:1) documentation says it is ELO rating at the start of the match2) that seems to be the preferable option (not sure there is a use case to support changing player ratings throughout the game.3) while it might be interesting to have the player rating at the end of the game (as it happens now when the game finishes), that could be another piece of information. In conclusion, I would expect the rating to reflect the player rating at the start of the game, and stay that way whether the game is in progress or finished. Proof:Match started on Juy 15th, when I had 1860 ELO daily, on July 22nd I lost a game and got to 1832, board API has current (as of July 22nd) or last ELO, and that will continue to change until the game finishes, then the ELO would not longer change and reflect my ELO at the end of the game (not the start of the game). https://api.chess.com/pub/match/913368/71 I understand rating history would be a future endpoint to enable point in time rating recovery or historical analysis, but still I would prefer the board endpoint rating to stay as of the start of the match. I understand last ELO might be more useful for some purposes, but I can recover that from the player stats. It would also be nice to add the rating at the end of the game. PD: Thans to @skelos for his valuable feedback!

The Public API initiative has enabled many potential scenarios where the data can be leveraged to benefit user communities here at the site. Sometimes the intended usage is quite specialized, other times there are very good ideas that could eventually be implemented by chess.com in the future. With the new API it is now easy to find good candidates for some clubs (e.g. national or regional teams playing in leagues) incrementing not only the membership but also the fit of new members and clubs. However, there are areas where automation is desirable. I can now identify that 10,000 chess.com members from my region have logged in in the last 24 hours, can screen the ones that are active on live chess or daily or 960 and are not members of the regional team, and can invite them manually. It would help a lot to have a way to invite members using the API if someone has a club admin login. Like: 1) Script sends 1 to 30 usernames plus invitation message to candidate member (individual requests or batch requests) Preconditions: Script has appropriate agent identification header and is able to send credentials in a couple of ways (admin user OR BOT USER and password through HTTPS connection) or (submitting API key linked to a human or bot user) The script has a way to take account of opt-out preferences Postconditions: The API returns whether the invitation was successfully sent or an exception (user is already a member or user does not accept invitations/messages, etc.) Alternatives to improve current status: 1) chess.com enables invitations to be sent to a larger number of users per day (e.g. 100 - currently capped at 30) I understand this could be done scrapping the UI and posting the forms with automated tools like selenium webdriver. It was easier in the old app, still possible in the new one. But I think it is a) more difficult; b) has less control to maintain opt-outs and c) not sure the terms of service covers usage of the API through automated scripts to send invitations, messages, etc. 2) We also send many PM via the app (or through whatsapp) when the time to move reaches a critical point. Automating those kind of messages would be another example of a possible API interaction, but I think that could easily be done by chess.com by sending alerts at 12, 8, 4, 1 hours before losing, if the user agrees to be chased... currently I understand there is an alert at 8 hours and another one later. I understand that providing the ability to send scripted invitations might be outside of the scope of the Public API, but it would help if some guidance is provided (e.g. do scrapping and automate posts through the UI | terms of service would accept or reject that | etc.) So far it takes a lot of human effort (but a very good benefit for us and for members of regional teams) something that could eventually be automated. Comments?

Hi, This isn't a bug as the API is working as documented, but it's on of those nice-to-have things that the website does and the API doesn't. https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player "status": "string", // account status: closed, closed:fair_play_violations, basic, premium, mod, staff Could we please have "closed" split into "closed" and "closed:abuse" for accounts for which the abuse icon is shown on the website? An analogous enhancement would be to add "closed: self_closed"(*) again in the interest of matching the website, but I don't need that today. (*) Space added after the colon to avoid emotion, obviously unwanted. Why I care about "closed" vs "closed:abuse" is for scoring a match according to a particular competition's rules. I am going to have to give a partial score in some situations with a list of boards in the match to examine manually as a workaround.

https://api.chess.com/pub/match/{ID} If player account closed for Fair Play or Abuse result is awarded to opponent in web page of match regardless of actual game result. API still shows actual result. Example: https://www.chess.com/club/matches/870770/games Board 7 Result shown as 0-2 (Adjusted due to closure) API returns 1-1 I haven't checked tournaments but may be the same issue.

In the previous months we introduce the recalculation of Matches and Tournaments scores if a player account was closed because of fair play infringiments.   While the recalculation does affect the scores it doesn't affect the game result, so it might be difficult for PubAPI clients to understand the real scores of a Match Board or Tournament Group. For this reason we are proposing to add some fields to expose the scores without touching the game results, as it happens in the Web counterpart.   Team Matches   Team Match endpoint "https://api.chess.com/pub/match/{matchId}"   We propose to add a "fair_play_removals" field that will be displayed for each team. It will enumerate the players whose accounts were closed during the match.   Example: (only relevats parts are displayed) {  "name":"Test Match", },  "teams":{    "team1":{      "name":"Group A",      "players":[       {         "username":"player5"       }      ],      "fair_play_removals":[        "player5"      ]    },     "team2":{      "name":"Group B",      "players":[       {         "username":"player6"       }      ],      "fair_play_removals":[      ]    }  }}   Team Match Board endpoint "https://api.chess-dev.com/pub/match/{matchId}/{board}" We propose to add a "board_scores" that will show scores for the two players:   Example: (only relevats parts are displayed) {  "board_scores":[   "player1": 0.5,   "player2": 1.5  ],  "games":[    // List of games  ]}     Tournaments   Tournament board "https://api.chess.com/pub/tournament/{url}/{round}/{group}"   We propose to add a "fair_play_removals" field for each team, that will display the list of players whose accounts were closed in the specific tournament's group. {   "fair_play_closures":[     "player4"  ],  "games":[     // List of games  ],  "players":[     {       "username":"player1",      "points":4,      "is_advancing":true    },    {       "username":"player2",      "points":2,      "is_advancing":false    },    {       "username":"player3",      "points":3,      "is_advancing":false    },    {       "username":"player4",      "points":3,      "is_advancing":false    }  ]}   Please leave your comments and proposals below!

https://api.chess.com/pub/player/johnlenin/games/archives {"archives":["https://api.chess.com/pub/player/johnlenin/games/2009/02",...,"https://api.chess.com/pub/player/johnlenin/games/2017/10","https://api.chess.com/pub/player/johnlenin/games/2017/11","https://api.chess.com/pub/player/johnlenin/games/2017/12","https://api.chess.com/pub/player/johnlenin/games/2018/01",...]} Bold above not found and returns a 404 error: https://api.chess.com/pub/player/johnlenin/games/2017/11: 404 Not Found {"message":"Game type code \"threecheck\" is invalid.","code":0}

I want to make an analysis on 4p games so i need to download some games. I would also need a way to get the first players on the leaderboard. Lets say first 50 or 100 so i can download their games if they are added in the API. Is this planed to be added to the API ?Regards,

Hi, Looking quickly at some player statistics for an ad-hoc report, and came across disagreement between the documentation and what data I received. https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player-stats says "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." (My emphasis.) https://api.chess.com/pub/player/zoki/stats {"chess_daily":{"last":{"rating":800,"rd":350},"record":{"win":0,"loss":0,"draw":0,"time_per_move":0,"timeout_percent":0}}... https://api.chess.com/pub/player/kadibyek/stats{"chess_daily":{"last":{"rating":800,"rd":350},"record":{"win":0,"loss":0,"draw":0,"time_per_move":0,"timeout_percent":0}}Same for daily_960 for that player: "chess960_daily":{"last":{"rating":800,"rd":350},"record":{"win":0,"loss":0,"draw":0,"time_per_move":0,"timeout_percent":0}}I've not checked others, but happened across more names I expect to be the same: @feraonback, @slahiry, @18jpde, @min134, @chdboy, @theeyeofhorus, and others. The workaround is to treat absence of the "chess_daily" record as 0W-0L-0D but if there is a record to be prepred for 0W-0L-0D. That's good eough for me, today, and I'm glad I'm in the habit of coding for "impossible" conditions! Best, Giles

@stephen_33 has started a topic for Python, intending to provide information about installation, troubleshooting, development, debugging and whatever else comes up. It may be that Python is more popular than perl these days; I don't know. I've been paid to write both but am definitely more experienced with perl since I was using it from version 2.x before Python existed. I am not going to try to duplicate Stephen's work here: for one, I am not expert enough with Windows to be able to troubleshoot all problems there, and for a second thing I prefer a text editor to write code in and a shell (Unix/Linux/OS X/MacOS) to run code in or console window (Windows) rather than an IDE (Integrated Development Environment). I know IDEs are the norm on Windows, but I've done most of my programming professionally for projects that targeted multiple operating systems, and IDEs are typically not portable.