Référence de l'API

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

Les notes des clubs et joueurs UEFA par HTTP. Les CSV se téléchargent sans clé ; les endpoints JSON demandent une clé gratuite. Toutes les données sont sous licence CC BY 4.0.

Se connecter pour obtenir une clé Essayer dans l'explorateur

Introduction

L'API est en lecture seule et renvoie du JSON en HTTPS. Chaque réponse place son contenu dans data et ajoute un objet meta avec la licence et la ligne d'attribution.

Les listes sont paginées avec page et per_page, et meta indique total, page et per_page. Les listes de notes portent aussi as_of, la date du classement d'origine.

URL de base

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

Réponse200application/json

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

Authentification

Envoyez votre clé dans l'en-tête X-API-Key. Tous les endpoints l'exigent, sauf les jeux de données ouverts. Une clé absente ou inconnue renvoie 401.

Créez et révoquez vos clés sur votre page de profil. Vous pouvez en avoir 3.

Gardez la clé sur un serveur. Le code envoyé au navigateur l'expose.

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

Réponse401application/json

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

Limites de requêtes

Chaque clé permet 10 requêtes par minute et 100 par jour. Le compteur quotidien repart à zéro à minuit UTC.

Les jeux de données ouverts ne demandent pas de clé et permettent 10 requêtes par minute par adresse IP. Au-delà d'une limite, l'API renvoie 429 avec Retry-After.

En-tête	Description
`X-RateLimit-Limit`	Requêtes autorisées par jour
`X-RateLimit-Remaining`	Requêtes restantes aujourd'hui
`X-RateLimit-Limit-Minute`	Requêtes autorisées par minute
`X-RateLimit-Remaining-Minute`	Requêtes restantes cette minute
`Retry-After`	Secondes d'attente, envoyé avec un 429

Réponse429application/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"
  }
}

Erreurs

Les erreurs utilisent les codes de statut HTTP et un corps JSON avec un code stable et un message lisible. Basez votre logique sur le code, pas sur le message.

Statut	Code	Description
401	`invalid_api_key`	L'en-tête X-API-Key est absent, mal formé ou inconnu.
403	`key_disabled`	La clé a été désactivée.
404	`not_found`	Aucun club, joueur ou saison ne correspond au chemin.
422	`validation_error`	Un paramètre a un type incorrect ou sort des bornes.
422	`invalid_date`	Une date n'est pas au format AAAA-MM-JJ, ou est dans le futur.
422	`invalid_season`	La saison n'est pas deux années consécutives, comme 2025-2026.
422	`filter_required`	Les matchs demandent au moins competition, season ou club.
429	`rate_limited`	Une limite est atteinte. Attendez le nombre de secondes de Retry-After.
503	`service_busy`	Un classement passé est en cours de calcul. Réessayez sous peu.

Réponse422application/json

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

Licence et attribution

Les données sont sous licence CC BY 4.0. Vous pouvez les partager et les adapter, y compris commercialement, en citant beyondELO, en renvoyant à la licence et en indiquant vos modifications. Utilisez cette ligne d'attribution :

Lire la licence

beyondELO (https://beyondelo.com)

Données ouvertes

Des fichiers CSV sans clé. Chacun est mis en cache une heure et porte la licence CC BY 4.0 dans son en-tête Link.

Lister les jeux de données

GET/v1/datasets

Les téléchargements CSV, avec leurs colonnes et la date de leur dernière mise à jour.

Sans clé

Paramètres

Aucun paramètre.

Erreurs

429rate_limited

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

Réponse200application/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)"
  }
}

CSV des notes de clubs

GET/v1/datasets/club-ratings.csv

Chaque club UEFA noté, avec sa note, son rang et son rang national, d'après l'instantané horaire.

Sans clé

Paramètres

Aucun paramètre.

Erreurs

429rate_limited

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

Réponse200text/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

CSV des notes de joueurs

GET/v1/datasets/player-ratings.csv

Chaque joueur classé, du meilleur au moins bon. Lu sur les données en direct : un changement de rang pendant le téléchargement peut répéter ou sauter une ligne.

Sans clé

Paramètres

Aucun paramètre.

Erreurs

429rate_limited

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

Réponse200text/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

CSV de l'historique des clubs

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

Chaque note de club enregistrée pendant une saison, triée par date puis par club.

Sans clé

Paramètres

Paramètre	Type	Description
`season`obligatoire	string	Saison en deux années consécutives, par exemple 2025-2026.

Erreurs

404not_found
422invalid_season
429rate_limited

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

Réponse200text/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

Lister les clubs

GET/v1/clubs

Les clubs UEFA notés, du meilleur au moins bon : les clubs classés par rang, puis les autres par note. rd est l'écart de la note et hfa l'avantage du terrain du club, en points.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`country`	string	Nom ou code du pays, par exemple England ou ENG.
`ranked`	boolean	true pour les clubs classés seulement, false pour les autres seulement.
`page`	integer	Numéro de page, à partir de 1.Par défaut 1
`per_page`	integer	Lignes par page, 1000 au plus.Par défaut 100

Erreurs

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"

Réponse200application/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
  }
}

Obtenir un club

GET/v1/clubs/{slug}

Un club avec sa note et son rang actuels.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`slug`obligatoire	string	Le slug du club, comme dans son adresse beyondelo.com.

Erreurs

401invalid_api_key
403key_disabled
429rate_limited
404not_found

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

Réponse200application/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"
  }
}

Historique d'un club

GET/v1/clubs/{slug}/history

La note d'un club après chaque match, de la plus ancienne à la plus récente.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`slug`obligatoire	string	Le slug du club, comme dans son adresse beyondelo.com.
`from`	date	Première date incluse, AAAA-MM-JJ.
`to`	date	Dernière date incluse, AAAA-MM-JJ.
`page`	integer	Numéro de page, à partir de 1.Par défaut 1
`per_page`	integer	Lignes par page, 1000 au plus.Par défaut 1000

Erreurs

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"

Réponse200application/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
  }
}

Classements

Classement des clubs

GET/v1/rankings/clubs

Les clubs classés à une date, du meilleur au moins bon. Sans date, vous obtenez le classement du jour.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`date`	date	Le classement à cette date, AAAA-MM-JJ. Par défaut aujourd'hui ; les dates futures sont refusées.

Erreurs

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"

Réponse200application/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
  }
}

Joueurs

Lister les joueurs

GET/v1/players

Les joueurs classés, du meilleur au moins bon.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`country`	string	Nationalité, par nom ou par code.
`club`	string	Seulement les joueurs du club ayant ce slug.
`page`	integer	Numéro de page, à partir de 1.Par défaut 1
`per_page`	integer	Lignes par page, 1000 au plus.Par défaut 100

Erreurs

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"

Réponse200application/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
  }
}

Obtenir un joueur

GET/v1/players/{slug}

Un joueur avec sa note et son rang actuels. Les joueurs non classés ont rank null.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`slug`obligatoire	string	Le slug du joueur, comme dans son adresse beyondelo.com.

Erreurs

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"

Réponse200application/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)"
  }
}

Historique d'un joueur

GET/v1/players/{slug}/history

La note d'un joueur après chaque match, de la plus ancienne à la plus récente.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`slug`obligatoire	string	Le slug du joueur, comme dans son adresse beyondelo.com.
`from`	date	Première date incluse, AAAA-MM-JJ.
`to`	date	Dernière date incluse, AAAA-MM-JJ.
`page`	integer	Numéro de page, à partir de 1.Par défaut 1
`per_page`	integer	Lignes par page, 1000 au plus.Par défaut 1000

Erreurs

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"

Réponse200application/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
  }
}

Pays et compétitions

Lister les pays

GET/v1/countries

Les pays UEFA ayant des clubs notés, selon la note moyenne de leurs clubs.

Clé d'API requise

Paramètres

Aucun paramètre.

Erreurs

401invalid_api_key
403key_disabled
429rate_limited

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

Réponse200application/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
  }
}

Lister les compétitions

GET/v1/competitions

Les compétitions notées, avec la première et la dernière saison couvertes. end_season vaut null tant que la compétition se poursuit.

Clé d'API requise

Paramètres

Aucun paramètre.

Erreurs

401invalid_api_key
403key_disabled
429rate_limited

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

Réponse200application/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
  }
}

Matchs

Lister les matchs

GET/v1/matches

Les matchs terminés, du plus récent au plus ancien, avec les notes des deux clubs avant et après. Donnez au moins un filtre.

Clé d'API requise

Paramètres

Paramètre	Type	Description
`competition`	string	Code de la compétition, par exemple ucl.
`season`	string	Saison en deux années consécutives, par exemple 2025-2026.
`club`	string	Seulement les matchs joués par le club ayant ce slug.
`page`	integer	Numéro de page, à partir de 1.Par défaut 1
`per_page`	integer	Lignes par page, 1000 au plus.Par défaut 100

Erreurs

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"

Réponse200application/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
  }
}