in_progress match board has diverged from the documentation

Sort:
skelos

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.

skelos

*bump*

skelos

2018-04-23 – 2018-05-14

The CHANGELOG entry for the above period mentions this endpoint, but I don't think the documentation for boards with in progress games has been updated although the data has changed.

The data now includes the PGN, but some of the data is duplicated in the per-game information ("match" for example), but I don't mind as long as the documentation and data agree).

"rating" appears to be back (thank you!).

 

My main point (possibly lot in the details in my first post) is that the data and documentation don't match. They're closer now, but not the same. I can work from the data (JSON is clear enough for that) but I'd like to have the data and documentation agree. Using undocumented features always makes me uneasy, as they have to be subject to change.

Granted the documentation here needs to change and we're still getting (and I'm OK with) breaking change when those are the best way to set something up long-term, here's a spot where the documentation is still not in sync.

$ ./lwp-dump https://api.chess.com/pub/match/824430/115

$VAR1 = {
          'games' => [
                       {
                         'start_time' => 1505459078,
                         'fen' => '8/4k3/5p2/4rP1R/2K5/7P/8/8 w - - 4 54',
                         'url' => 'https://www.chess.com/daily/game/174773358',
                         'turn' => 'white',
                         'rated' => bless( do{\(my $o = 1)}, 'JSON:P::Boolean' ),
                         'rules' => 'chess',
                         'pgn' => '[Event "TMCL 2017 Play-Gp. ALPHA P1 R6: Asger\'s Great Viking Warriors v. The Chess Club: Open. - Board 115"]
[Site "Chess.com"]
[Date "2017.09.15"]
[Round "1"]
[White "DomDeDomDom"]
[Black "anna1705"]
[Result "*"]
[WhiteElo "1736"]
[BlackElo "1764"]
[TimeControl "1/259200"]
[StartTime "07:04:38"]
[Link "https://www.chess.com/daily/game/174773358"]

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 4. Ba4 Nf6 5. O-O Nxe4 6. d4 b5 7. Bb3 d5 8. dxe5 Be6 9. Be3 Be7 10. c3 O-O 11. Nbd2 Bg4 12. h3 Bh5 13. g4 Bg6 14. Nd4 Nxe5 15. N2f3 Nxf3+ 16. Qxf3 Qd6 17. Rfd1 c6 18. Nxc6 Qxc6 19. Bxd5 Qf6 20. Bxe4 Bxe4 21. Qxe4 Rfe8 22. Bd4 Qh4 23. Qf3 Rad8 24. Kg2 Bf6 25. Bxf6 Qxf6 26. Qxf6 gxf6 27. Kf3 Rxd1 28. Rxd1 Re6 29. b3 Kg7 30. a4 bxa4 31. bxa4 Rc6 32. Rd3 Rc4 33. Ke3 Rxa4 34. Rd4 Ra3 35. Rd3 Kg6 36. f4 h6 37. c4 Ra1 38. c5 f5 39. Rd6+ f6 40. gxf5+ Kxf5 41. Rd5+ Ke6 42. Rd6+ Ke7 43. Rb6 h5 44. f5 a5 45. Re6+ Kf7 46. Ra6 a4 47. c6 Rc1 48. Kd4 Ke7 49. Rxa4 Rxc6 50. Ra7+ Kd6 51. Rh7 Rc5 52. Rxh5 Re5 53. Kc4 Ke7 *',
                         'match' => 'https://api.chess.com/pub/match/824430',
                         'last_activity' => 1526215661,
                         'black' => 'https://api.chess.com/pub/player/anna1705',
                         'move_by' => 1526474861,
                         'time_class' => 'daily',
                         'white' => 'https://api.chess.com/pub/player/domdedomdom',
                         'time_control' => '1/259200'
                       },
                       {
                         'end_time' => 1518825302,
                         'white' => {
                                      'rating' => 1636,
                                      'username' => 'anna1705',
                                      'result' => 'resigned',
                                      '@id' => 'https://api.chess.com/pub/player/anna1705'
                                    },
                         'time_control' => '1/259200',
                         'time_class' => 'daily',
                         'black' => {
                                      '@id' => 'https://api.chess.com/pub/player/domdedomdom',
                                      'result' => 'win',
                                      'username' => 'DomDeDomDom',
                                      'rating' => 1755
                                    },
                         'pgn' => '[Event "TMCL 2017 Play-Gp. ALPHA P1 R6: Asger\'s Great Viking Warriors v. The Chess Club: Open. - Board 115"]
[Site "Chess.com"]
[Date "2017.09.15"]
[Round "-"]
[White "anna1705"]
[Black "DomDeDomDom"]
[Result "0-1"]
[WhiteElo "1636"]
[BlackElo "1755"]
[TimeControl "1/259200"]
[Termination "DomDeDomDom won by resignation"]
[StartTime "07:04:38"]
[EndDate "2018.02.16"]
[EndTime "23:55:02"]
[Link "https://www.chess.com/daily/game/174773360"]

1. e4 e5 2. Nf3 Nc6 3. d4 exd4 4. Nxd4 Nf6 5. Nc3 Bb4 6. Qd3 O-O 7. Bd2 Bxc3 8. Bxc3 Nxe4 9. Be2 Re8 10. O-O d5 11. Be1 Bf5 12. Nxf5 Qg5 13. Ng3 Qe5 14. Nxe4 dxe4 15. Qb3 Nd4 16. Qe3 Nxc2 17. Qc1 Nxa1 18. Bc3 Qe6 19. Qxa1 Rad8 20. b3 f6 21. Bc4 Rd5 22. Bxd5 Qxd5 23. h3 Qc5 24. Bd4 Qe7 25. Be3 f5 26. Rd1 h6 27. Qd4 b6 28. Qc4+ Kh7 29. Qd5 Qf6 30. Bf4 c5 31. Rd2 g5 32. Bh2 f4 33. Qd6 Re6 34. Qd5 e3 35. fxe3 fxe3 36. Qd3+ Kg7 37. Re2 Qa1+ 0-1',
                         'match' => 'https://api.chess.com/pub/match/824430',
                         'rules' => 'chess',
                         'rated' => $VAR1->{'games'}[0]{'rated'},
                         'fen' => '8/p5k1/1p2r2p/2p3p1/8/1P1Qp2P/P3R1PB/q5K1 w - - 4 38',
                         'url' => 'https://www.chess.com/daily/game/174773360',
                         'start_time' => 1505459078
                       }
                     ]
        };