RFC: Match Data

This Request For Comments covers a new set of endpoints to provide information about team matches, and lists of matches particpated in by player and by club.

Matches will be referenced by their internal numeric ID. This ID is guaranteed unique and unchanging, but our internal IDs may change format in the future and so a new ID may be provided at that time. For this reason it advisable to always access the match endpoint first by retrieving the URL from list of player's matches or club's matches endpoint.

/pub/match/{id}

This is the data representation of the match itself. The data returned for players changes depending on the status of the match.

If the match is in its registration phase:

{
    "name": string, 
    "url": "URL", // the URL of the match on the website
    "rules": string, // game variant information (e.g., "chess960")
    "description": string, // description
    "start_time" : timestamp, //time of start or autostart, depending on settings 
    "end_time": timestamp,
    "settings": {
      "rules": "chess",
      "time_class": "daily",
      "time_control": "1/86400",
      "min_team_players": 1,
      "min_required_games": 0,
      "autostart": false
    },
    "status": string, // {finished|registration|in_progress},
    "boards": integer, // number of boards
    "teams": [
        "team1": {
            "@id": "URL", // API URL for the club profile
            "name": "string", // club name
            "score": score,
            "players": [
                {
                    "username": "username", 
                    "board": "url", // url of board
                    "rating": 1355, //rating of player
                    "timeout": 25, //timeout percentage
                    "status": "basic", //status of user 
                }
            ]
        },
        "team2": {
            "@id": "URL", // API URL for the club profile
            "name": "string", // club name
            "score": score,
            "players": [
                {
                    "username": "username",
                    "board": "url", // url of board
                    "rating": 1355, //rating of player
                    "timeout": 25, //timeout percentage
                    "status": "closed:fair_play_violations", //status of user 
                }
            ]
        }
    ]   
}

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

{
    "name": string, 
    "url": "URL", // the URL of the match on the website
    "rules": string, // game variant information (e.g., "chess960")
    "description": string, // description
    "start_time" : timestamp,
    "end_time": timestamp,
    "settings": {
       "rules": "chess",
       "time_class": "daily",
       "time_control": "1/86400",
       "min_team_players": 1,
       "min_required_games": 0,
       "autostart": false
    },
    "status": string, // {finished|registration|in_progress},
    "boards": integer, // number of boards
    "teams": [
        "team1": {
            "@id": "URL", // API URL for the club profile
            "name": "string", // club name
            "score": score,
            "players": [
                {
                    "username": "username", 
                    "board": "url", // url of board
                    "played_as_white": "win",
                    "played_as_black": "lose", 
                    "stats": "url", //url to player's stats 
                }
            ]
        },
        "team2": {
            "@id": "URL", // API URL for the club profile
            "name": "string", // club name
            "score": score,
            "players": [
                {
                    "username": "username",
                    "board": "url", // url of board
                    "stats": "url", //url to player's stats 
                    "played_as_white": "lose",
                    "played_as_black": "win", 
                }
            ]
        }
    ]   
}

/pub/match/{id}/{board}

This is the data representation of a single board in a match. Only in-progress or finished games will be included, so there may be one or two games in this list.

{
    "board": board number,
    "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", // the player's result, if game's finished
               "@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", // the player's result, if game's finished
                "@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")
        }
    ],
}

/pub/player/{username}/matches

This is the list of player's matches, divided by "finished", "in_progress" and "registered":

{
    "finished": [
        /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "club": "URL", // URL of player's club endpoint
            "results": [
                "played_as_white": "win", //result of game played as white
                "played_as_black": "win" //result of game played as black
            ],
            "board": "URL", // URL of PubAPI match board endpoint
        } 
    ],
    "in_progress": [
       /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "club": "URL", // URL of player's club endpoint
            "board": "URL", // URL of PubAPI match board endpoint
        } 
    ],
    "registered": [
       /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "club": "URL", // URL of player's club endpoint
        } 
    ]
  }
}

/pub/club/{url}/matches

This is the data representation of a clubs's matches, divided by "finished", "in_progress" and "registered":

{
    "finished": [
        /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "opponent": "URL", // URL of opponent's club endpoint
            "result": "win", //result of match 
        } 
    ],
    "in_progress": [
       /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "opponent": "URL", // URL of opponent's club endpoint
        } 
    ],
    "registered": [
       /** List of matches */
        {
            "name": "Name of match",
            "url": "URL", // URL of match on web site
            "@id": "URL", // URL of PubAPI match endpoint
            "opponent": "URL", // URL of opponent's club endpoint
        } 
    ]
  }
}

Does this endpoint get you what's needed for your goals, tools, and services? Are there related data we missed that are essential? If possible, please include specific examples of how you intend to use the data, especially if you request that we change this output in some way.

Suggestion:

"players": [
{
"username": username,
"board": url of board,
"timeout": timeout percentage

}

Please add timeout % details in there... so admins for Leagues could directly check those without having to check the whole list of members.

I'd like to see timeout too, but then I want rating as well ... so perhaps leaving the player without too much detail and we can fetch what else we need.

More particularly, I want to see board data during registration, to compare numbers of boards and ratings to work out how well balanced a match is. I had a script that did that for V2 (cut&paste, edit a bit, run script -- very much a prototype).

For matches without auto-start deciding when a match is balanced is helpful for knowing when to lock. For matches with auto-start it's even more important if the team is one of those who really like to win matches, or for more moderate teams if the match is "important" e.g. one of the league competitions.

Edit: Changed sign-up to "registration" and "players" to "boards" to better fit the nomenclature being used.

@puremind, most scripts I envisage are going to dip into multiple endpoints. As long as looking up a match and then making per-player (both sides) queries isn't going to hit a rate limit on large matches (one team I am in has had multiple ~300 board matches this year) then I encourage simplicity at the chess.com endpoints and any necessary complexity in client access.

My reason is that what details you (or I) want may not be what others want, and we risk "cluttering" the endpoints with too much information that will take time to put together and then be ignored by most users.

Caution: I may be thinking too much in "relational database" mode. I know when I started working with LDAP I had to learn how it worked and some habits of thought were unhelpful to me. I did learn, but I admit to feeling some frustration until I "got it" and then I was fine.

On match level please add registration-start-date.

And at the same time I would appreciate if score on the given board can be already part of main match resourse, so I dont need to call all boards frequentlynto get scores of specific players.

I think a lot of tournaments (world league, team match champions league) would also like to identify fair play closures.  Abuse closures and self-closures probably don't matter as much.

Good point, @MGleason. Yes, TMCL particularly wants "Fair Play" closures as they negate any points won and add a penalty.

However, this returns to how much of the per-user endpoint should be included here, versus fetching per-username information as required.

@skelos makes a good point as we try to do not replicate data among endpoints. But we also try to find a trade-off between clean endpoints and performance. In some cases it may be easier for us to add an information that is already available rather than ask the user to make thousands of calls to retrieve the same data.

To better understand your needs and how often refresh the data:

•  the timeout percentage (requested by @puremind) is only reviewed when the player joins, or if it needs to be reviewed just prior to locking and starting the match?
•  the per-board scores (requested by @Dale00007) would only be useful during the match? 

@MGleason we are going to check if we can access fair play closures that are meaningful to this endpoint, thank you for the suggestion.

For TMCL at least just prior to locking a match, and I expect most admins to be checking reasonably often. TMCL matches usually have a relatively lengthy sign-up period, and knocking out unsuitable players ASAP gives a better understanding of how balanced the match is.

Of course, teams in TMCL aren't looking for balance as much as unfavourable balance, but you get the idea. :-)

No comment re per-board scores.

Fair play closures (or as they're rare, account closures and a followup call to retrieve any reason) will be wanted to calculate league as opposed to apparent scores as the match progresses.

TMCL (which is the only one I know a little about) strips any points won, and awards two penalty points to the player paired with a "Fair Play" closed account, unless that player is also closed for Fair Play in which the paring is scored as 0:0.

Thanks for considering our comments; I for one appreciate it. (In a job one time I was asked forc comments, spent several days working some up, and then was told, "Oh, no, we had to ask, but it's too late: we've already implemented the new feature, and can't consider any comments now!" As you may imagine, "words were spoken".)

@andreamorandini - yes, it would be needed only when match is ongoing. Once completed I would just call all boards once and get final results

TMCL will want post-final results at the cutoff date for converting provisional results to final (scores will change due to additional "Fair Play" account closures), but that I expect to be small beer compared to the other uses we all have.

Please review the description of the match endpoint. 

We have revised the structure in order to provide two different sets of data for players:

- the current rating and timeout percentage are available during registration to aid in matchmaking, but such current stats are misleading when viewing archived matches.

- once the games begin, the rating snapshot of the player should be found on the individual games played.

Please note that these stats may be less current than those listed in the player stats link, by up to 24 hours.

That change seems OK to me. Timeout data and rating within 24 hours of current is close enough for practical purposes, I believe.

I am particularly keen to get access to per-player matches (and vote chess games, but that's definitely secondary) to help in figuring out who is "dead wood" and even more for managing timeouts.

Being "active" in a team by posting notes is not always going to be enough, and "active" (as defined for the club endpoint) is not very precisely defined, which I believe I noted there so this is an aside only.

Breaking change: please note that we have changed the output of Player and Club matches endpoint in order to provide more information about finished matches. These changes were made in order to help user's find some stats without having to request too many endpoints.

The new set of team matches endpoints is out to be tested.

For more details see:

• Player's team Matches,
• Club's Team Matches,
• Team Match,
• Team Match board

Feel free to continue commenting on those endpoints and requests improvements!

Using /pub/match/{id} for a match in "registration" state (testing with 858774) I am not seeing "name" for either "team1'" or "team2".

I do see "url" for each team, so I'll follow that and see where it takes me.

Correction: @id, not url. I want the API not the website!

I don't think we're out of the woods on the bug fixes here yet.

Sill using 858774 as my development test case, for team1 ("Black Stone") player @pawnrook4 I get:

$VAR1 = {

          'username' => 'pawnrook4',

          'timeout' => '27.27',

          'status' => 'basic'

        };

When looking at the website, the player clearly has a daily rating as implied by having a non-zero timeout value: