Public API

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.

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 steve.bush@neosys.com Cirencester

Subject to change without notice currently

Player Name Search using sound-alike (100ms)

To get a list of all players with names sounding like "John Smythe"
https://www.ecfrating.org.uk/v2/new/api.php?v2/players/fuzzy_name/john smythe

One or two words can be given in any order.

Player Name Search using exact word-stems (200ms)

To get a list of all players with names containing "Joh..." and "Smi..." including all John Smiths
https://www.ecfrating.org.uk/v2/new/api.php?v2/players/name/joh smi

One or two words or word stems can be given in any order.

Player's Info (10ms)

To get general info about player 120787J (10ms)
https://www.ecfrating.org.uk/v2/new/api.php?v2/players/code/120787

Player's Rating (1ms)

To get the ECF Official Standard Rating of player 120787J effective on 2020-07-05
https://www.ecfrating.org.uk/v2/new/api.php?v2/ratings/Standard/120787/2020-07-05

Replace "Standard" with "Rapid" to get rapid rating instead.

Player's Games (10ms)

To get the 100 most recent rapid games of player 120787J
https://www.ecfrating.org.uk/v2/new/api.php?v2/games/Rapid/player/120787/limit/100

Replace "Rapid" with "Standard" to get standard games instead.

All Rated Players(1sec 2Mb)

Latest:
JSON : https://www.ecfrating.org.uk/v2/new/api.php?v2/players_ratings
CSV : https://www.ecfrating.org.uk/v2/new/api.php?v2/players_ratings_csv

Historical: Example for 1st July 2020

* 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.
* Only Jan 1 and Jul 1 is available from 1994 to Jul 2020. Thereafter 1st of every month is available.

JSON : https://www.ecfrating.org.uk/v2/new/api.php?v2/players_ratings/2020-07-01
CSV : https://www.ecfrating.org.uk/v2/new/api.php?v2/players_ratings_csv/2020-07-01

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.
5. "games_36m" means number of games played in the previous 36 months
6. "Prior" provides the same info from the previous month.

Top Players (350ms)

To get the top 100 players table
https://www.ecfrating.org.uk/v2/new/list_top_players.php?domain=S&age_limit=none&age_col=age&nation=ENG&gender=both&type=rating&format=json

To get various other top 100 tables use the following arguments.

Meaning Parameter  Possible Arguments (Choose one and only one!)
Standard or Rapid &domain =S =R
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

Club Name Search using exact word-stems (5ms)

To get a list of all clubs with name containing word or word stems "LOND" including club names mentioning LONDON
https://www.ecfrating.org.uk/v2/new/api.php?v2/clubs/name/LOND

One or two words or word stems can be given in any order.

Club Info (10ms)

To get simple info about club code 3330 (1ms)
https://www.ecfrating.org.uk/v2/new/api.php?v2/clubs/code/3330

All Active Clubs (200ms)

https://www.ecfrating.org.uk/v2/new/api.php?v2/clubs/all_active

HTTP Error Codes

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.

[Index]