CCRL Rating API

This is a restful HTTP API to query the CCRL rating lists for computer chess engines. It can be used to fetch overall statistics about any chess engine on any of the three lists:

• CCRL 40/4
• CCRL 40/40
• CCRL 40/4 Fisher Random Chess (FRC)

There is also the option to get badges from shields.io with dynamicly loaded ratings.

API Documentation

To use the API you have two options:

1. Clone this repository and run the web service localy on your own machine/server.
2. Use the server hosted by me.

The latter option is currently available at the following IP:

    http://104.196.164.195

The reliability of this service is not guaranteed, and the IP could be subject to change, although this will be kept as stable as possible. If the badges at the top of this README have rendered succesfully, the service is available.

JSON Queries

Query a list for a given engine:

GET /<List>/<Name>

Response:

{
    "rank": string  # Rank of the list. May be a range, e.g. "1-5".
    "name": string   # Full name of engine.
    "rating": integer  # ELO rating.
    "rating-pluss": integer  # Upper uncertainty in rating.
    "rating-minus": integer  # Lower uncertainty in rating.
    "score": float  # Percentage of average points per game (Win = 1, Draw = 1/2).
    "average-opponent-diff": float  # Average rating difference of opponents.
    "draw-rate": float  # Percentage draw rate.
    "games-played": integer  # Number of games recorded for this engine.
    "link": url  # Link to the CCRL rating list queried.
}

The <List> must be one of the following:

• 4040 for CCRL 40/40
• 404 for CCRL 40/4
• 404FRC for CCRL 40/4 FRC

The <Name can be any uniquely identifying string found on the corresponding CCRL rating list. The API will find the first entry where <Name> is found within the full name.

Example:

GET /4040/Goldfish%201.13.0
{
    "rank": "351-353",
    "name": "Goldfish 1.13.0 64-bit",
    "rating": 2044,
    "rating-pluss": 22,
    "rating-minus": -22,
    "score": 49.5,
    "average-opponent-diff": 5.5,
    "draw-rate": 26.6,
    "games-played": 751
    "link": "http://ccrl.chessdom.com/ccrl/4040"
}

GitHub Badges

Optional URL parameters are available to the JSON queries that will yield a shields.io badge with the rating information.

Parameters:

• badge: Set to any non-falsy value to return a shields.io badge instead of the JSON
• label: Left-side text. Default is CCRL Rating (remember to replace spaces with %20)
• rating_prefix: Right-side text to prepend to the rating. Default is no prefix.
• rating_postfix: Right-side text to append to the rating. Default is no postfix.
• color: Color of right-side of badge. May be any of the below names (red, blue etc) or a hex number. Default is orange.
• link: Specify what the badge should link to. Default is the corresponding CCRL rating list.
• Any other parameters are forwarded to shields.io, see their API documentation there for additional options available, including cacheSeconds, logo, labelColor and more.

Example:

GET /4040/Goldfish?badge=1&label=Engine%20Rating&rating_postfix=%20ELO&color=informational