The ECF Rating System has a public application program interface (API) that allows other software systems to make quick ad hoc requests for information using HTTPS and JSON.
It also allows the download of complete ratings lists equivalent to those in the previous system.
Any queries about these services should be sent to [email protected] in the first instance.
There is a limit on the amount of processing time per day per internet class C network address. The maximum processing time is currently 10 minutes per day, reset every midnight GMT, but may be changed without notice. Processing time and limits are provided in every JSON response.
19th July 2020 [email protected] CirencesterOne or two words can be given in any order; spaces should be replaced with + signs for reliability.
FIDE and NM titles added to download May 2024.
FIDE and NM titles added to download May 2024.
FIDE and NM titles added to download May 2024.
Replace "S" with "R" or "B" to get OTB rapid or blitz ratings respectively instead, and with "SW", "RW", or "BW" to get online standard, rapid, or blitz ratings respectively.
Replace "Rapid" with "Standard" to get standard games instead, or with "Blitz" to get blitz games.
Online games are not published.
* Right click, choose "copy link location" and paste to a new tab. Change date to desired date and press Enter.
* Only the ratings, categories and number of games are historical. All other info is current latest available.
* Monthly over-the board ratings are available from July 2020. Six-monthy (January and July) ratings are available
for Jan 2012 to Jan 2020,
and annual July ratings only for the years 1994 to 2011.
* Online ratings are available monthly from Jan 2021.
* OTB Blitz ratings are available monthly from Dec 2021.
1. Ratings are based on all games up to but excluding the given date provided in the json or file name for csv. Games dated thereafter have no effect.
2. "Original" ratings are calculated at the end of every month and will never change thereafter.
3. "Revised ratings" are recalculated nightly based on all submissions committed.
4. "Category" is the same as under the old system. A-F * etc, subject to adjustments made due to Covid (see here).
5. "games_36m" means number of games played in the previous 36 months
6. "Prior" provides the same info from the previous month.
To get various other top 100 tables use the following arguments.
| Meaning | Parameter | Possible Arguments (Choose one and only one!) |
|---|---|---|
| List | &domain | =S =R =B for OTB, =SW =RW =BW for Online |
| England or World | &nation | =ENG =ALL |
| Age group | &age_limit | =none =U20 =U19 =U18 =U17 =U16 =U15 =U14 =U13 =U12 =U11 =U9 =U8 =U7 =19 =18 =17 =16 =15 =14 =13 =12 =11 =10 =9 =8 =7 =6 =50plus =55plus =60plus =65plus =70plus =75plus =80plus |
| ECF or FIDE "age" | &age_col | =age =age31dec |
| Sex | &gender | =both =male =female |
| Rank by Rating, Improvement or Activity | &type | =rating =improvement =activity |
| &format=json is mandatory | &format | =json |
Field name for FIDE and NM titles amended for consistency from playing_title to title May 2024.
One or two words or word stems can be given in any order.
In all cases a detailed explanatory message will be given in the json response.
| Code | Name | Description |
|---|---|---|
| 400 | Bad Request | The server cannot or will not process the request due to an apparent client error e.g. malformed request syntax. |
| 404 | Not Found | The requested resource could not be found but may be available in future. |
| 500 | Internal Server Error | An unexpected condition was encountered in the server. Similar requests by the client are likely to suffer the same result in the short term. |