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.