RFC: Player Stats

This Request For Comments covers a new per-player endpoint to provide current playing stats for each game type, and changes to the data values for games-related endpoints. Historical rating data will be obtainable from the game archives.

Please note: These endpoints should provide the same data as the website stats pages, but some aspects of these API stats will be coded from scratch; as such, we want to treat any difference as a bug and would appreciate reports covering such cases.

/pub/player/{username}/stats

Each timeclass and rules variant will have a "stats" block of approximately the same structure, identified by a key in the format of "<rules>_<timeclass>". This is always true; all livechess variants are in the "blitz" timeclass, and so even though it seems redundant these will be named like "bughouse_blitz" and "chess960_blitz".

In addition, we will be using the website timeclass names: "rapid" in place of "standard," and "bullet" in place of "lightning." The games endpoints will be updated to reflect this (see note below).

Therefore the player-stats DTO is a collection of named stats DTOs, like so:

{
    "chess_daily":{ /* stats block */ },
    "chess960_rapid":{ /* stats block */ },
    "bughouse_blitz":{ /* stats block */ }
}

Timeclass options are: daily, rapid (previously "standard"), blitz, bullet (previously "lightning"). Rules options are: chess, chess960, crazyhouse, bughouse, kingofthehill, losers, oddschess, threecheck. Not all combinations are available. Many livechess variants only track the "last" rating info and so their stats blocks will have no "best" or "tournament" blocks. If the player has never been in a tournament, that block is not present. If the player has never won a game, the "best" block is not present.

We will only deliver stats blocks for class/rules combinations that the player has actually played — no default entries should be delivered. This means that players who have just registered and not yet played will have an empty stats object.

Each stats block contains:

{
    "last":{
        "rating":1500,
        "rd":56.7,
        "game":"web URL",
        "date":123456789
    },
    "best":{
        "rating":1500,
        "game":"web URL",
        "date":123456789
    },
    "record":{
        "win":1,
        "loss":2,
        "draw":3,
        "time_per_move":56160, // daily time class only, measured in seconds
        "timeout_percent":23 // daily time class only; note: only past 3 months (same as web UI)
    },
    "tournament":{
        "points":1,
        "count":1,
        "withdraw":2,
        "best_finish":12, // only if greater than 3
        "finished":[ // only available if the player has placed in top 3 at least once
            { /* after tournament endpoint: place, tournament link */ }
        ]
    }
}

Breaking Change

/pub/player/{username}/games
/pub/player/{username}/games/YYYY/MM

All game endpoints will have a change to the time_class values, to use the website terms for livechess "rapid" (previously "standard") and "bullet" (previously "lightning").

Does this endpoint get you what's needed for your stats and ratings projects? 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.

It's sufficient for me.

Possibly there could be parm to call just specific game type as for me I need especially only Daily ratings. So using parm to get only specific rating can reduce traffic slightly.

It might be interesting to be able to get rating as of a particular date.  That would let us see how rating changes over time, which would be of interest from a cheater-hunt perspective to identify those cases of sudden onset of genius.

Well,  this does definitely provide easy access for those projects that, for example, need to get the recent rating, or a time per-move. Though, I do agreed with @MGleason that it would be interesting -not only that, but very useful- to get a rating by particular date. 

This would be useful for someone who is, for example, trying to get rating changes over a certain period of time -x number of months for example- combined with a fast check on the number of a certain type of game -like blitz or 960- played in the same period. 

Such random-access to ratings would require a scan of the past games of that type. We have compiled this for the purpose of delivering the ratings graph on the website, however it's not in a format that makes it immediately usable for the API; I will look into it.

I had pointed out: "Historical rating data will be obtainable from the game archives." Essentially, developers like you who need that information can already gather it. Is that process not sufficient?

Based on @Dale00007 's comment and your, it seems like the rating is the super-important stat, and the rest is just spice. I'll see what else we might put together for that.

Technically, yes, that is sufficient and in fact is what I have been doing / using over this past week... but really, it would be helpful if the API could just provide some of this data instead. That is probably just me being lazy.

I can imagine that other stats are important too for different user stories - maybe would be interested for myself too in case I am trying to build something more. But as of now its not my target so I have plan to consume just ratings and generally just daily, chess960, blitz/bullet/rapid live standard ... rest I will not be processing.