Forum

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.

An interesting case: https://api.chess.com/pub/player/integrator/games/archives {"archives":["https://api.chess.com/pub/player/integrator/games/2008/05","https://api.chess.com/pub/player/integrator/games/2008/12","https://api.chess.com/pub/player/integrator/games/2009/07","https://api.chess.com/pub/player/integrator/games/2009/08"," ...]} https://api.chess.com/pub/player/integrator/games/2009/07 {"games":[...{"url":"https://www.chess.com/daily/game/23594327","pgn":"[Event \"The truth shall set u free! - Board 1\"]\n[Site \"Chess.com\"]\n[Date \"2009.07.10\"]\n[Round \"-\"]\n[White \"integrator\"]\n[Black \"madz123456\"]\n[Result \"1-0\"]\n[WhiteElo \"2324\"]\n[BlackElo \"2078\"]\n[TimeControl \"1/259200\"]\n[Termination \"integrator won on time\"]\n[StartTime \"19:32:57\"]\n[EndDate \"2009.08.02\"]\n[EndTime \"06:02:08\"]\n[Link \"https://www.chess.com/daily/game/23594327\"]\n\n1. e4 e5 2. f4 exf4 3. Bc4 Nf6 4. Nc3 c6 5. d4 d5 6. exd5 cxd5 7. Bb5+ Nc6 8. Bxf4 Bd6 9. Nge2 O-O 10. O-O Be6 11. a3 Ne4 12. Kh1 Be7 13. Nxe4 dxe4 14. c4 a6 15. Bxc6 1-0","time_control":"1/259200","end_time":1249192928,"rated":true,"fen":"r2q1rk1/1p2bppp/p1B1b3/8/2PPpB2/P7/1P2N1PP/R2Q1R1K b - - 1 15","start_time":1247254377,"time_class":"daily","rules":"chess","white":{"rating":2324,"result":"win","@id":"https://api.chess.com/pub/player/integrator","username":"integrator"},"black":{"rating":2078,"result":"timeout","@id":"https://api.chess.com/pub/player/madz123456","username":"madz123456"},"match":"https://api.chess.com/pub/match/10901"}]} https://api.chess.com/pub/player/integrator/games/2009/08 {"games":[{"url":"https://www.chess.com/daily/game/23594327","pgn":"[Event \"The truth shall set u free! - Board 1\"]\n[Site \"Chess.com\"]\n[Date \"2009.07.10\"]\n[Round \"-\"]\n[White \"integrator\"]\n[Black \"madz123456\"]\n[Result \"1-0\"]\n[WhiteElo \"2324\"]\n[BlackElo \"2078\"]\n[TimeControl \"1/259200\"]\n[Termination \"integrator won on time\"]\n[StartTime \"19:32:57\"]\n[EndDate \"2009.08.02\"]\n[EndTime \"06:02:08\"]\n[Link \"https://www.chess.com/daily/game/23594327\"]\n\n1. e4 e5 2. f4 exf4 3. Bc4 Nf6 4. Nc3 c6 5. d4 d5 6. exd5 cxd5 7. Bb5+ Nc6 8. Bxf4 Bd6 9. Nge2 O-O 10. O-O Be6 11. a3 Ne4 12. Kh1 Be7 13. Nxe4 dxe4 14. c4 a6 15. Bxc6 1-0","time_control":"1/259200","end_time":1249192928,"rated":true,"fen":"r2q1rk1/1p2bppp/p1B1b3/8/2PPpB2/P7/1P2N1PP/R2Q1R1K b - - 1 15","start_time":1247254377,"time_class":"daily","rules":"chess","white":{"rating":2324,"result":"win","@id":"https://api.chess.com/pub/player/integrator","username":"integrator"},"black":{"rating":2078,"result":"timeout","@id":"https://api.chess.com/pub/player/madz123456","username":"madz123456"},"match":"https://api.chess.com/pub/match/10901"}]} Same game, is right to be in the August archive but should not be in July as well. I only noticed this because the player has 8W-0L-0D as his record, and my script picking games out of the archive when told "everything" found nine games. After a little head scratching I dug in and found the extra. I will add some checking code to my script to make sure it doesn't inadvertently get duplicates (which could happen if I tell it the wrong files, so now that I've thought of it it's a useful enhancement). I will post if I happen across other instances.

Carrying this over from https://www.chess.com/clubs/forum/view/live-games-missing-from-archives as it is a separate problem and has persisted for several days. [Site "Chess.com"] [Date "????.??.??"] [Round "-"] EndDate and EndTime are present (and for daily games I mostly want EndDate for sorting as the web archive interface does) but this has to be a bug. Any game database wants the Date value. Thanks.

https://api.chess.com/pub/player/{username}/is-online Although this function seems to work pretty well I have seen instances of players on line for at least 30 mins flagged as false and at least one instance of a player who was offline for at least 4 hours flagged as true.

Hi, I think this is a new bug, although we've had instances of missing games before. This time I'm not seeing live games (only daily) in at least one month's archive for a member. Please compare: https://www.chess.com/games/archive?gameOwner=other_game&username=lisa1998&gameType=live&gameTypeslive%5B%5D=blitz&gameResult=&opponent=&opening=&color=&gameTourTeam=&gameTitle=&timeSort=desc&rated=rated&startDate%5Bdate%5D=&endDate%5Bdate%5D=&fen=&ratingFrom=&ratingTo=&search= With: https://api.chess.com/pub/player/lisa1998/games/2018/04 (output in next post) There are no live games in that archive (which was in the archive list; I do fetch that first). An example missing game: https://www.chess.com/live/game/2729294752?username=lisa1998

Are there plans for Live Team Matches end point to be added. As far as I can see https://api.chess.com/pub/matches/{ID} only covers daily matches. or am I missing something?

This isn't quite "minor errata" in the documentation so I'm starting a new thread. https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-board documents: { "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 }, "black": { // details of the black-piece player: "username": "string", // the username "rating": 1942, // 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 }, "url": "string", // URL of this game "fen": "string", // current FEN "pgn": "string", // final PGN, if game's finished "start_time": 1254438881, // timestamp of the game start (Daily Chess only) "end_time": 1254670734, // timestamp of the game end, if game's finished "time_control": "string", // PGN-compliant time control "time_class": "string", // time-per-move grouping, used for ratings "rules": "string", // game variant information (e.g., "chess960") "eco": "string", //URL pointing to ECO opening (if available), "match": "string", //URL pointing to team match (if available) } ], } what I appear to get instead contains more data moved into the per-game information, but I don't see the result (or end_time) and I think I need the result ... am I now supposed to get those from the game url? (Which is a website URL not an api.chess.com URL, but can probably be translated.) I personally also liked the "start of match" rating too, but for predicting match outcomes without running an engine over incomplete games the players' current ratings are arguably better than their starting ratings, so that's a wash, mostly. What I do get (live example, games in progress): 'games' => [ { 'fen' => '2r1r3/4kppp/p7/1ppR4/4n3/P3PN1P/1P3PP1/2R2K2 b - - 0 1', 'start_time' => 1524953098, 'rules' => 'chess', 'last_activity' => 1524953098, 'turn' => 'black', 'time_class' => 'daily', 'move_by' => 1525212298, 'time_control' => '1/259200', 'black' => 'https://api.chess.com/pub/player/acnologia01', 'white' => 'https://api.chess.com/pub/player/wombadom', 'rated' => bless( do{\(my $o = 1)}, 'JSON::​PP::Boolean' ), 'url' => 'https://www.chess.com/daily/game/193456876', 'match' => 'https://api.chess.com/pub/match/890216' }, { 'time_control' => '1/259200', 'white' => 'https://api.chess.com/pub/player/acnologia01', 'black' => 'https://api.chess.com/pub/player/wombadom', 'rated' => $VAR1->{'games'}[0]{'rated'}, 'url' => 'https://www.chess.com/daily/game/193456874', 'match' => 'https://api.chess.com/pub/match/890216', 'rules' => 'chess', 'fen' => '2r1r3/4kppp/p7/1ppR4/4n3/P3PN1P/1P3PP1/2R2K2 b - - 0 1', 'start_time' => 1524953098, 'move_by' => 1525212298, 'time_class' => 'daily', 'last_activity' => 1524953098, 'turn' => 'black' } ] }; I'm a little at a loss now how to predict a match result. I can do it for matches which are in "registration" state, it is trivial for a match in "finished" state but "in_progress" looks hard. I'm pretty sure I could figure more of this out by looking at more advanced matches with some boards finished, but the #1 point of this (lengthy) post is intended to be that the per-match-board documentation doesn't currently match the endpoint.

Hi, Missing from the current games endpoint but present in the archives are: "tournament": "string", //URL pointing to tournament (if available), "match": "string", //URL pointing to team match (if available) Is there any reason not to include these in a player's current games? The information is available on the website (player profile->games->current games to get a list) and wouldn't bulk out the data volume I wouldn't think. It might depend how hard it is to incorporate, however: a) It's useful to figure out who is a tournament player, who is a team match player and who is both b) Sometimes it's useful to know what event a game is being played in, without going via a match or tournament endpoint first. Regards, Giles (who was about to enhance a script to check for types of games, but now can't)

https://api.chess.com/pub/player/lindisfarnex/games/2017/07: 404 Not Found

Hello everyone, I think it would be interesting to add to the player data profile endpoint (or player stats) the vacation time remaining.

Has there ever been an effort to document the API by generating an OpenAPI spec? This would allow some automatic doc generation, help ensure the team putting out the API is keeping docs up to date, can generate client libraries in a bunch of languages, even have an interactive API explorer. Thoughts?