README

FIDE ratings scraper

This package offers an interface (both as a CLI and/or as a server API) to get chess player ratings information in a programative way.

FIDE is the International Chess Federation. They feature a ratings sub-domain where players may check their international ELO rating (in different categories), their perfomance history, et cetera.

Features

Access chess players' FIDE ratings information in a programative way
Easily expose an API to access ratings resource scraped and parsed directly from FIDE ratings website

Installing

Using npm:

$ npm i -g fide-ratings-scraper

Usage

$ fide-ratings-scraper <operation> [...args]

operation:
- get: Obtain a resource
  - info: Obtain a player's full available info
  - personal-data: Obtain a player's personal data
  - rank: Obtain a player's rank
  - elo: Obtain a player's ELO (in different categories)
  - history: Obtain a player's ELOs history
- api: Start app as a web API

Example

$ fide-ratings-scraper get info 1503014

$ fide-ratings-scraper api

API

GET Player Full Info

/player/{fide_number}/info

Get all the information provided by FIDE about the player.

{
    "name": "Doe, John",
    "federation": "Portugal",
    "birth_year": 1980,
    "sex": "Male",
    "title": "None",
    "standard_elo": 1700,
    "rapid_elo": 1650,
    "blitz_elo": 1750,
    "world_rank_all_players": 180000,
    "world_rank_active_players": 135200,
    "national_rank_all_players": 760,
    "national_rank_active_players": 325,
    "continental_rank_all_players": 132400,
    "continental_rank_active_players": 62405
}

GET Player Personal Data

/player/{fide_number}/personal-data

Get the player's personal data.

{
    "name": "Doe, John",
    "federation": "Portugal",
    "birth_year": 1980,
    "sex": "Male",
    "title": "None",
}

GET Player Rank

/player/{fide_number}/rank

Get the player's rank in different ranking lists.

{
    "world_rank_all_players": 180000,
    "world_rank_active_players": 135200,
    "national_rank_all_players": 760,
    "national_rank_active_players": 325,
    "continental_rank_all_players": 132400,
    "continental_rank_active_players": 62405
}

GET Player ELO

/player/{fide_number}/elo

Get the player's ELO in all the categories.

{
    "standard_elo": 1700,
    "rapid_elo": 1650,
    "blitz_elo": 1750,
}

GET Player History

/player/{fide_number}/history

Get a full list of all the player's ELO ratings (in all the categories) along the past years, ordered by date (most recent first).

[
    {
        "date": "2019-Oct",
        "numeric_date": 201910,
        "standard": "1700",
        "num_standard_games": "1",
        "rapid": "1650",
        "num_rapid_games": "0",
        "blitz": "1750",
        "num_blitz_games": "0"
    },
    {
        "date": "2019-Sep",
        "numeric_date": 201909,
        "standard": "1692",
        "num_standard_games": "1",
        "rapid": "1610",
        "num_rapid_games": "9",
        "blitz": "1750",
        "num_blitz_games": "0"
    },
    {
        "date": "2019-Aug",
        "numeric_date": 201908,
        "standard": "1680",
        "num_standard_games": "2",
        "rapid": "1610",
        "num_rapid_games": "0",
        "blitz": "1720",
        "num_blitz_games": "2"
    }
]

GET Player Full Info Including History

/player/{fide_number}/info?include_history=true

Get all the information provided by FIDE about the player, including the previous rating change history.

{
    "name": "Doe, John",
    "federation": "Portugal",
    "birth_year": 1980,
    "sex": "Male",
    "title": "None",
    "standard_elo": 1700,
    "rapid_elo": 1650,
    "blitz_elo": 1750,
    "world_rank_all_players": 180000,
    "world_rank_active_players": 135200,
    "national_rank_all_players": 760,
    "national_rank_active_players": 325,
    "continental_rank_all_players": 132400,
    "continental_rank_active_players": 62405,
    "history": [
    {
        "date": "2019-Oct",
        "numeric_date": 201910,
        "standard": "1700",
        "num_standard_games": "1",
        "rapid": "1650",
        "num_rapid_games": "0",
        "blitz": "1750",
        "num_blitz_games": "0"
    }]
}

Tests

To run the test suite, install the project's dependencies and run npm test:

$ npm install
$ npm test

To run mutation tests:

$ npm run test:mutation

Running API

A running sample may be found at https://fide-ratings-scraper.herokuapp.com/, deployed using Heroku.

License

MIT

Usage no npm install needed!