match endpoints feedback

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-club-matches

 "result": "win" // result of the match{win,lose}

Draw?

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player-matches

"finished": [
...

"results": [
                "played_as_white": "win", //result of game played as white
                "played_as_black": "win" //result of game played as black
            ],

I'm not sure I want the results here. I think I'd rather have links to the games, as if I find a loss I'm going to want to know whether it was a loss on time or not, and if so what the date was. The date of the game(s) is/are more important than the date the match ended: if someone has two timeouts three days apart or eight timeouts over the same period it's probably the same incident. (Hospital visit, hurricane, didn't care, whatever.) As an admin it's useful to distinguish the players who are dropping games here and there relatively constantly, from those who drop a bunch at once. The former are more of a problem than the latter.

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile

Link not quite right? Takes me to the top of the API page.

"rules": string, // game variant information (e.g., "chess960")

Would it not be more consistent to use "Variant" for this? That's what's used in the PGNs. If "rules" is consistent with other endpoints, keep it? I've been doing game selection post-download as discussed elsewhere and use "Event", "Variant" and "TimeControl" from the PGNs so far.

Data format of match in its registration phase:

 "timeout": 25, //timeout percentage
                    "status": "closed:fair_play_violations", //status of user 

I doubt we'll see closed accounts in registration phase, but if this information is being pulled up here along with timeout %, then I'd like to see it pulled up into in-progress and completed matches too.

To calculate a TMCL (Team Match Chamionship League) result for a match in progress or completed but stil provisional, player status is needed, as penalties are applied to boards which have fair play closures.

In general, why separate registration phase from the others? What is "end time" for  match in registration phase?

Auto-start or not and minimum and maximum number of boards are items I don't see. All those are useful to know.

V3 provides via the web interface the uernames of the originating admins. Why leave them out? (If there's a good reason, OK ... as I can't think of a real need to get at that data programatically. But as a rule of thumb everything I can see (other than perhaps posts) for a match that I can see on the web I'd like to be able to get programatically.)

Another missing item: has one or other team locked? Any attempt to balance boards or even report imbalance wants that one, as once a team has locked there's usully little time to work on it before having to lock and start.

Data format in others phases of match (in progress, finished, closed):

Finished vs. closed? I don't understand that.

https://api.chess.com/pub/match/{ID}/{board} 

In the games list, result can be dug out of the PGN if the game is finished, but is it worth having without digging into the PGNs? 1-0, 0-1, 1/2-1/2, or *?

If start time and end time are given, result might as well be in there too? I think it would be more ueful, but others may have uses for start time and end time that I don't. (Or haven't thought of yet.)

Sorry those comments are a bit scrambled. I'm in recovery phase from a migraine (second in a week) so I merely hope it makes some sense. Fine writing is beyond me for the moment.

@skelos Thank you for your prompt reply! I've corrected the typos you have found in documentation.

About your other questions:

1. Player matches: the games details are in the board endpoint, that you can reach via the URL. We prefer to not link full details of games here because of caching performance (games details bring lots of cache invalidations).
2. Fair play penalties: there will be some news soon about calculation of penalties in team matches, so stay tuned,
3. Stats in in-progress and completed matches: in completed matches we provide a link to the user's stats because we don't keep a snapshot of those stats. About "in-progress" I can check the feasibility.
4. Stats missing: I think that we can add the missing information you require "auto-start", "min-max number of boards", "admin" and "team locked",
5. Results in board matches: this endpoint expose the same information of https://www.chess.com/news/view/published-data-api#pubapi-endpoint-games-archive , that gives a more detailed result for the two players ('win', 'checkmated', 'resigned' etc.). I'll confront internally if we can provide the PGN result here.

For your other questions I've to confront internally before giving you an inaccurate answer. Get well for now!

Thanks @andreamorandini.

I'm not sure how your point #3 came about; possibly something I asked for is in player stats but so far (other than timeout %) I've not been interested.

Point #5: I use that endpoint; I'm not using it in any very sophisticated manner as I want the PGNs, and once I'm parsing them anyway pulling out the data I want from them rather than storing it in parallel from the endpoint doesn't seem worth the complexity. (So far.)

#4 would be good.

#2, interesting.

#1 OK. I don't know your database schema or how readily it translates to the endpoints you're providing. Whether a player lost by timeout or not is important, but it's not something that will be looked up often. Proceeding to the board endpoint is going to work out satisfactorily. (It has to beat going through completed matches manually, as I spent time doing at the weekend!)

Cheers,

Giles

Hi. Thanks for moving in with this endpoint. Unfortunately I am quite busy and behind with my work on previous items, so I am not sure when I can get to review in such details as @skelos.

Just 2 quick notes:

1) some matches in registrations seems to fail to load - 

https://api.chess.com/pub/match/857270

2) could you still add to club match endoint result of the match on the given board? At least for games in progress. As I explained earlier. For ongoing games I (and I expect other developers too) load results frequently, so calling all boards one by one just to check result can be inefficient.  

@Dale00007 We have fixed the bug that returned the error you were experiencing with the "Prague Open Challenge - Slow Pace XI".

About your request: we understand that now you have all in one page so it may look a step backward to have to call all the boards. We will rethink about that and I'll let you know.

Besides two bugs reported in separate forums I found need of three data for matches in the registration:

a) min/max rating

b) min/max players

c) scheduled start date

Breaking changes: please be aware that we have slightly changed the Team Match endpoint:

• We have added a "settings" property that contains most important match settings (rules, time_class, time_control, min/max rating, min/max players etc.),
• we have renamed the "timeout" field of players to "timeout_percentage" in order to keep the same naming that we used in Player's stats endpoint.

I've just hit a relative biggie for me.

I'm writing a report on which players in a team are active.

Partly because what being "active" for a team is is not (yet) well defined, and partly to be able to state categorically: "This is the last match you played for us in, X months ago."

(I want vote chess too, and to know who voted when, and to me vote chess is more important than tournaments but yeah, numbers count and merely because I like vote chess doesn't mean a lot of people do, and we have people who play only "Let's Play" games, only tournaments and only team matches among those who play daily games. I get it, I get it!)

I can get a list of a team's completed matches, but to find the date of those matches (a six year old match will rarely be interesting) I am going to have to look up the match.

Yes, obviously I can cache old finished matches. If (as I suspect I will need to) I set up a website to host the odd tool, no problem.

If I can, I would prefer to distribute a script to administrators that they can run on their own machines, even if the output is not so pretty. If I fall under a tram, they've still got the script. Most of the people I'm working with think interpreting PGN Spy results is major expertise; actually coding something ... woah!

Thus, while in principle I think caching old results is the "right" answer it's not so good for a utility that is distributed to unsophisticated computer users. People who use computers to play chess, maybe buy something online sometimes and for the die-hards who haven't given up email due to spam, send email.

Food for thought more than a specific request. This report doesn't have to be stupendously fast (the alternative is manually looking through those matches, which with V3 particularly is s-l-o-w for the big ones) so a couple of minutes runtime I can sell if I have to.

For matches in registration state, is there a reason not to provide "Registration Open" via the match endpoint?

This is another instance of different data being accessible on the website to what is available from api.chess.com. I think I'm on record as desiring where it's feasible to be able to get anything the website provides via api.chess.com as well, and this item is static data set when the match is created.

@Dale00007 Now you should be able to start seeing results in match endpoint, see for example: https://api.chess.com/pub/match/857270 (I'll update the documentation later, so take this as a spoiler  ).

@skelos You should be able find a property called "locked" in the team properties ?  So if the match is in registration phase but Team1 is locked, you know that the registration isn't open anymore (for that team). Please try and let me know if it works for you.

Thanks Andrea. I shall look.

Feedback will be delayed a week or so:

1. Real life is moving from "busy" to "extremely busy" this week
2. I have team administrators interested and providing suggestions for a team "activity report" so want to keep moving with it before they lose interest!

The team match endpoint doesn't include a self-referential @id element.

For matches in registration state this would be particularly useful; a really stupid script can go through updating them without knowing what reports they're needed for. Or even add them to a queue to keep the major data accesses single-threaded. (Yes, we're allowed three now. I think I want one most of the time, and keep the second and third for more "interactive" data accesses.)

"time_class": "string", // time-per-move grouping, used for ratings

That one confuses me. I've looked at one match that doesn't contain it. The closest I can think of is time-per-move in player statistics, but that seems a stretch to have wound up here.

Is it intended for brevity that different details are provided as examples for 'team1' and 'team2'?

I would rather see a complete list under 'team1' and simply note that 'team2' has the same per-player data.

Heading into wishlist territory (and definitely an enhancement request and your back-end systems may not retain the data):

• A list of players who registered (i.e. are active for the club) but missed a board would be helpful
• Even more helpful would be those who missed due to rating limit instead of not being matched to an opponent.

Under "settings" I do not see minimum or maximum rating.

OK, I got it, we have live matches now too. Perhaps examples of "daily", "live" (or whatever) would help guide people to the right answer, and "live" might be "blitz" or "rapid" rather than simply "live"?

This was requested earlier in the thread. I'd like in all stages of a match, as it helps guess who was eligible to play and who wasn't when looking back.

Is there a guarantee for the team match endpoint that the team shown on the left on the website will be "team1" and the team shown on the right will be "team2"?

I would like to be able to rely on that; reporting with the order of teams reversed would look odd.

*ping* for the left == team1 or not question