https://github.com/bsamseth/ccrl-api

HTTP API to query the CCRL rating lists for computer chess engine ratings. (*Note*: This API is not currently hosted anywhere and requires you to run your own instance of it. See README)
https://github.com/bsamseth/ccrl-api

api badge-generator chess chess-engine ratings rest-api shields

Last synced: 3 months ago
JSON representation

HTTP API to query the CCRL rating lists for computer chess engine ratings. (*Note*: This API is not currently hosted anywhere and requires you to run your own instance of it. See README)

Host: GitHub
URL: https://github.com/bsamseth/ccrl-api
Owner: bsamseth
License: mit
Created: 2019-04-21T15:05:46.000Z (about 6 years ago)
Default Branch: master
Last Pushed: 2024-04-17T02:50:07.000Z (about 1 year ago)
Last Synced: 2025-02-06T12:16:02.739Z (5 months ago)
Topics: api, badge-generator, chess, chess-engine, ratings, rest-api, shields
Language: Python
Homepage:
Size: 49.8 KB
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# CCRL Rating API

This is a restful HTTP API to query the [CCRL](http://ccrl.chessdom.com/ccrl/404/) 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](http://ccrl.chessdom.com/ccrl/404/)
* [CCRL 40/40](http://ccrl.chessdom.com/ccrl/4040/)
* [CCRL 40/4 Fisher Random Chess (FRC)](http://ccrl.chessdom.com/ccrl/404FRC)

There is also the option to get badges from [shields.io](https://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:

```text
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:

``` text
GET //

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 `` must be one of the following:

* `4040` for CCRL 40/40
* `404` for CCRL 40/4
* `404FRC` for CCRL 40/4 FRC

The `` is found within the full name.

__Example__:
``` text
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](https://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](https://shields.io/), see their API documentation there for additional options available, including `cacheSeconds`, `logo`, `labelColor` and more.