API reference

Name: beyondELO player ratings
Creator: beyondELO
License: https://creativecommons.org/licenses/by/4.0/

UEFA club and player ratings over HTTP. The CSV downloads need no key; the JSON endpoints need a free one. All data is licensed CC BY 4.0.

Introduction

The API is read-only and returns JSON over HTTPS. Every response puts its payload in data and adds a meta object with the licence and the attribution line.

Lists are paged with page and per_page, and meta carries total, page and per_page. Rating lists also carry as_of, the date of the board they come from.

Base URL

https://public-api.beyondelo.com/v1

Response200application/json

{
  "data": {
    "status": "ok"
  },
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)"
  }
}

Authentication

Send your key in the X-API-Key header. Every endpoint needs it except the open datasets. A missing or unknown key returns 401.

Create and revoke keys on your profile page. You can hold up to 3.

Keep the key on a server. Code shipped to a browser exposes it.

curl "https://public-api.beyondelo.com/v1/clubs/arsenal" \
  -H "X-API-Key: $BEYONDELO_KEY"

Response401application/json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key"
  }
}

Rate limits

Each key may make 10 requests a minute and 100 a day. The daily count resets at midnight UTC.

The open datasets need no key and allow 10 requests a minute from each IP address. Past any limit the API returns 429 with Retry-After.

Header	Description
`X-RateLimit-Limit`	Requests allowed per day
`X-RateLimit-Remaining`	Requests left today
`X-RateLimit-Limit-Minute`	Requests allowed per minute
`X-RateLimit-Remaining-Minute`	Requests left this minute
`Retry-After`	Seconds to wait, sent with a 429

Response429application/json

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 0

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Errors

Errors use HTTP status codes and a JSON body with a stable code and a readable message. Branch on the code, not on the message.

Status	Code	Description
401	`invalid_api_key`	The X-API-Key header is missing, malformed or unknown.
403	`key_disabled`	The key has been disabled.
404	`not_found`	No club, player or season matches the path.
422	`validation_error`	A parameter has the wrong type or is out of range.
422	`invalid_date`	A date is not YYYY-MM-DD, or lies in the future.
422	`invalid_season`	The season is not two consecutive years, like 2025-2026.
422	`filter_required`	Matches need at least one of competition, season or club.
429	`rate_limited`	A rate limit was reached. Wait for Retry-After seconds.
503	`service_busy`	A past ranking is being computed. Retry shortly.

Response422application/json

{
  "error": {
    "code": "invalid_season",
    "message": "season must look like 2025-2026 (two consecutive years)"
  }
}

Licence and attribution

The data is licensed CC BY 4.0. You may share and adapt it, commercially too, if you credit beyondELO, link to the licence and say what you changed. Use this attribution line:

Read the licence

beyondELO (https://beyondelo.com)

Open datasets

CSV files that need no key. Each is cached for an hour and carries the CC BY 4.0 licence in its Link header.

List datasets

GET/v1/datasets

The CSV downloads, with their columns and the date each was last updated.

No key needed

Parameters

No parameters.

Errors

429rate_limited

curl "https://public-api.beyondelo.com/v1/datasets"

Response200application/json

{
  "data": [
    {
      "name": "club-ratings",
      "url": "/v1/datasets/club-ratings.csv",
      "columns": [
        "rank",
        "country_rank",
        "slug",
        "name",
        "country_code",
        "elo",
        "rd",
        "hfa",
        "is_ranked",
        "last_match_date",
        "as_of"
      ],
      "updated": "2026-11-01",
      "description": "Current rating, rank and country rank of every rated UEFA club (hourly snapshot)."
    },
    {
      "name": "player-ratings",
      "url": "/v1/datasets/player-ratings.csv",
      "columns": [
        "rank",
        "slug",
        "name",
        "country_code",
        "club",
        "position",
        "elo",
        "as_of"
      ],
      "updated": "2026-11-01",
      "description": "Every ranked player with the current rating, best first."
    },
    {
      "name": "club-elo-history",
      "url": "/v1/datasets/club-elo-history/{season}.csv",
      "columns": [
        "date",
        "club",
        "elo",
        "rd"
      ],
      "updated": null,
      "description": "Club ratings recorded in one season, e.g. 2025-2026."
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)"
  }
}

Club ratings CSV

GET/v1/datasets/club-ratings.csv

Every rated UEFA club with its rating, rank and rank in its country, from the hourly snapshot.

No key needed

Parameters

No parameters.

Errors

429rate_limited

curl -o club-ratings.csv "https://public-api.beyondelo.com/v1/datasets/club-ratings.csv"

Response200text/csv

rank,country_rank,slug,name,country_code,elo,rd,hfa,is_ranked,last_match_date,as_of
1,1,arsenal,Arsenal,ENG,2143,73.9944080273676,47.9473267152183,true,2026-10-24,2026-11-01
2,1,bayern-munich,Bayern Munich,GER,2095,78.1585982480217,50.0911638547463,true,2026-10-25,2026-11-01
3,1,paris-saint-germain,Paris Saint-Germain,FRA,2092,75.6086753081906,38.0483502418775,true,2026-10-30,2026-11-01

Player ratings CSV

GET/v1/datasets/player-ratings.csv

Every ranked player, best first. It is read from live data, so a rank change during the download can repeat or skip a row.

No key needed

Parameters

No parameters.

Errors

429rate_limited

curl -o player-ratings.csv "https://public-api.beyondelo.com/v1/datasets/player-ratings.csv"

Response200text/csv

rank,slug,name,country_code,club,position,elo,as_of
1,lamine-yamal,Lamine Yamal,ESP,Barcelona,RW,2275,2026-11-01
2,harry-kane,Harry Kane,ENG,Bayern Munich,CF,2256,2026-11-01
3,ousmane-dembele,Ousmane Dembele,FRA,Paris Saint-Germain,CF,2247,2026-11-01

Club rating history CSV

GET/v1/datasets/club-elo-history/{season}.csv

Every club rating recorded in one season, ordered by date and then club.

No key needed

Parameters

Parameter	Type	Description
`season`required	string	Season as two consecutive years, for example 2025-2026.

Errors

404not_found
422invalid_season
429rate_limited

curl -o 2024-2025.csv "https://public-api.beyondelo.com/v1/datasets/club-elo-history/2024-2025.csv"

Response200text/csv

date,club,elo,rd
2024-03-31,arsenal,2000,66.78311941349256
2024-04-03,arsenal,2002,67.13726422701903
2024-04-06,arsenal,2011,66.96197342076347

Clubs

List clubs

GET/v1/clubs

Rated UEFA clubs, best first: ranked clubs by rank, then unranked clubs by rating. rd is the rating deviation and hfa the club's home advantage, both in rating points.

Needs an API key

Parameters

Parameter	Type	Description
`country`	string	Country name or code, for example England or ENG.
`ranked`	boolean	true for ranked clubs only, false for unranked clubs only.
`page`	integer	Page number, from 1.Default 1
`per_page`	integer	Rows per page, at most 1000.Default 100

Errors

401invalid_api_key
403key_disabled
429rate_limited
422validation_error

curl -G "https://public-api.beyondelo.com/v1/clubs" \
  -d country=ENG \
  -d ranked=true \
  -d per_page=2 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "slug": "arsenal",
      "name": "Arsenal",
      "country": "England",
      "country_code": "ENG",
      "uefa_id": "52280",
      "elo": 2143,
      "rd": 73.9944080273676,
      "hfa": 47.9473267152183,
      "rank": 1,
      "country_rank": 1,
      "is_ranked": true,
      "last_match_date": "2026-10-24"
    },
    {
      "slug": "manchester-city",
      "name": "Manchester City",
      "country": "England",
      "country_code": "ENG",
      "uefa_id": "52919",
      "elo": 2037,
      "rd": 70.0925676619534,
      "hfa": 51.6742858123645,
      "rank": 5,
      "country_rank": 2,
      "is_ranked": true,
      "last_match_date": "2026-10-24"
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "as_of": "2026-11-01",
    "total": 25,
    "page": 1,
    "per_page": 2
  }
}

Get a club

GET/v1/clubs/{slug}

One club with its current rating and rank.

Needs an API key

Parameters

Parameter	Type	Description
`slug`required	string	The club's slug, as in its beyondelo.com address.

Errors

401invalid_api_key
403key_disabled
429rate_limited
404not_found

curl "https://public-api.beyondelo.com/v1/clubs/arsenal" \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": {
    "slug": "arsenal",
    "name": "Arsenal",
    "country": "England",
    "country_code": "ENG",
    "uefa_id": "52280",
    "elo": 2143,
    "rd": 73.9944080273676,
    "hfa": 47.9473267152183,
    "rank": 1,
    "country_rank": 1,
    "is_ranked": true,
    "last_match_date": "2026-10-24"
  },
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "as_of": "2026-11-01"
  }
}

Club rating history

GET/v1/clubs/{slug}/history

A club's rating after each match, oldest first.

Needs an API key

Parameters

Parameter	Type	Description
`slug`required	string	The club's slug, as in its beyondelo.com address.
`from`	date	First date to include, YYYY-MM-DD.
`to`	date	Last date to include, YYYY-MM-DD.
`page`	integer	Page number, from 1.Default 1
`per_page`	integer	Rows per page, at most 1000.Default 1000

Errors

401invalid_api_key
403key_disabled
429rate_limited
404not_found
422invalid_date
422validation_error

curl -G "https://public-api.beyondelo.com/v1/clubs/arsenal/history" \
  -d from=2026-10-01 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "date": "2026-10-10",
      "elo": 2143,
      "rd": 75.1398962114201
    },
    {
      "date": "2026-10-13",
      "elo": 2146,
      "rd": 75.17221192369435
    },
    {
      "date": "2026-10-18",
      "elo": 2142,
      "rd": 74.94831715206651
    },
    {
      "date": "2026-10-21",
      "elo": 2147,
      "rd": 74.0646972086874
    },
    {
      "date": "2026-10-24",
      "elo": 2143,
      "rd": 73.88066354332346
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 5,
    "page": 1,
    "per_page": 1000
  }
}

Rankings

Club rankings

GET/v1/rankings/clubs

The ranked clubs on a date, best first. Without a date you get today's board.

Needs an API key

Parameters

Parameter	Type	Description
`date`	date	The board on this date, YYYY-MM-DD. Defaults to today; future dates are rejected.

Errors

401invalid_api_key
403key_disabled
429rate_limited
422invalid_date
503service_busy

curl -G "https://public-api.beyondelo.com/v1/rankings/clubs" \
  -d date=2026-10-01 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "slug": "arsenal",
      "name": "Arsenal",
      "country": "England",
      "country_code": "ENG",
      "uefa_id": "52280",
      "elo": 2140,
      "rd": 75.5430105775723,
      "hfa": 47.4219471539218,
      "rank": 1,
      "country_rank": 1,
      "is_ranked": true,
      "last_match_date": "2026-09-19"
    },
    {
      "slug": "bayern-munich",
      "name": "Bayern Munich",
      "country": "Germany",
      "country_code": "GER",
      "uefa_id": "50037",
      "elo": 2110,
      "rd": 80.2567376578145,
      "hfa": 49.7829941581144,
      "rank": 2,
      "country_rank": 1,
      "is_ranked": true,
      "last_match_date": "2026-09-18"
    },
    …
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "as_of": "2026-10-01",
    "total": 527
  }
}

Players

List players

GET/v1/players

Ranked players, best first.

Needs an API key

Parameters

Parameter	Type	Description
`country`	string	Nationality, by name or code.
`club`	string	Only players at the club with this slug.
`page`	integer	Page number, from 1.Default 1
`per_page`	integer	Rows per page, at most 1000.Default 100

Errors

401invalid_api_key
403key_disabled
429rate_limited
422validation_error

curl -G "https://public-api.beyondelo.com/v1/players" \
  -d per_page=2 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "slug": "lamine-yamal",
      "name": "Lamine Yamal",
      "country_code": "ESP",
      "club": "Barcelona",
      "position": "RW",
      "elo": 2275,
      "rank": 1
    },
    {
      "slug": "harry-kane",
      "name": "Harry Kane",
      "country_code": "ENG",
      "club": "Bayern Munich",
      "position": "CF",
      "elo": 2256,
      "rank": 2
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 7820,
    "page": 1,
    "per_page": 2
  }
}

Get a player

GET/v1/players/{slug}

One player with the current rating and rank. Unranked players have rank null.

Needs an API key

Parameters

Parameter	Type	Description
`slug`required	string	The player's slug, as in their beyondelo.com address.

Errors

401invalid_api_key
403key_disabled
429rate_limited
404not_found

curl "https://public-api.beyondelo.com/v1/players/harry-kane" \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": {
    "slug": "harry-kane",
    "name": "Harry Kane",
    "country_code": "ENG",
    "club": "Bayern Munich",
    "position": "CF",
    "elo": 2256,
    "rank": 2
  },
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)"
  }
}

Player rating history

GET/v1/players/{slug}/history

A player's rating after each match, oldest first.

Needs an API key

Parameters

Parameter	Type	Description
`slug`required	string	The player's slug, as in their beyondelo.com address.
`from`	date	First date to include, YYYY-MM-DD.
`to`	date	Last date to include, YYYY-MM-DD.
`page`	integer	Page number, from 1.Default 1
`per_page`	integer	Rows per page, at most 1000.Default 1000

Errors

401invalid_api_key
403key_disabled
429rate_limited
404not_found
422invalid_date
422validation_error

curl -G "https://public-api.beyondelo.com/v1/players/harry-kane/history" \
  -d from=2026-10-01 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "date": "2026-10-10",
      "elo": 2221,
      "rd": 90.2
    },
    {
      "date": "2026-10-13",
      "elo": 2235,
      "rd": 90.05
    },
    {
      "date": "2026-10-17",
      "elo": 2240,
      "rd": 90.17
    },
    {
      "date": "2026-10-21",
      "elo": 2263,
      "rd": 88.2
    },
    {
      "date": "2026-10-25",
      "elo": 2256,
      "rd": 88.09
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 5,
    "page": 1,
    "per_page": 1000
  }
}

Countries and competitions

List countries

GET/v1/countries

The UEFA countries with rated clubs, by the average rating of their clubs.

Needs an API key

Parameters

No parameters.

Errors

401invalid_api_key
403key_disabled
429rate_limited

curl "https://public-api.beyondelo.com/v1/countries" \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "name": "England",
      "code": "ENG",
      "avg_elo": 1839,
      "club_count": 25,
      "last_rated_at": "2026-10-31"
    },
    {
      "name": "Spain",
      "code": "ESP",
      "avg_elo": 1707,
      "club_count": 26,
      "last_rated_at": "2026-10-31"
    },
    …
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 55
  }
}

List competitions

GET/v1/competitions

The rated competitions, with the first and last season covered. end_season is null while a competition is running.

Needs an API key

Parameters

No parameters.

Errors

401invalid_api_key
403key_disabled
429rate_limited

curl "https://public-api.beyondelo.com/v1/competitions" \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "code": "ucl",
      "name": "UEFA Champions League",
      "tier": "continental_club",
      "country": null,
      "first_season": "1992-1993",
      "end_season": null
    },
    {
      "code": "eng.1",
      "name": "Premier League",
      "tier": "domestic_league",
      "country": "England",
      "first_season": "1993-1994",
      "end_season": null
    },
    …
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 32
  }
}

Matches

List matches

GET/v1/matches

Finished matches, newest first, with both clubs' ratings before and after. Give at least one filter.

Needs an API key

Parameters

Parameter	Type	Description
`competition`	string	Competition code, for example ucl.
`season`	string	Season as two consecutive years, for example 2025-2026.
`club`	string	Only matches played by the club with this slug.
`page`	integer	Page number, from 1.Default 1
`per_page`	integer	Rows per page, at most 1000.Default 100

Errors

401invalid_api_key
403key_disabled
429rate_limited
422filter_required
422invalid_season
422validation_error

curl -G "https://public-api.beyondelo.com/v1/matches" \
  -d competition=ucl \
  -d club=arsenal \
  -d per_page=1 \
  -H "X-API-Key: $BEYONDELO_KEY"

Response200application/json

{
  "data": [
    {
      "id": "750f31e0-1e54-4d12-997e-6e74e01ae44f",
      "date": "2026-10-21",
      "competition": "ucl",
      "season": "2026-2027",
      "stage": "League Phase",
      "matchday": 3,
      "home": "Bayern Munich",
      "away": "Arsenal",
      "home_score": 2,
      "away_score": 2,
      "home_elo_before": 2091,
      "home_elo_after": 2090,
      "away_elo_before": 2146,
      "away_elo_after": 2147
    }
  ],
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)",
    "total": 233,
    "page": 1,
    "per_page": 1
  }
}