API-Referenz

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

Wertungen von UEFA-Vereinen und -Spielern über HTTP. Die CSV-Downloads brauchen keinen Schlüssel, die JSON-Endpunkte einen kostenlosen. Alle Daten stehen unter CC BY 4.0.

Anmelden und Schlüssel holen Im Explorer testen

Einführung

Die API ist schreibgeschützt und liefert JSON über HTTPS. Jede Antwort legt ihren Inhalt in data ab und ergänzt ein meta-Objekt mit Lizenz und Namensnennung.

Listen werden mit page und per_page geblättert; meta enthält total, page und per_page. Wertungslisten enthalten zudem as_of, das Datum der zugrunde liegenden Tabelle.

Basis-URL

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

Antwort200application/json

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

Authentifizierung

Senden Sie Ihren Schlüssel im Header X-API-Key. Alle Endpunkte außer den offenen Datensätzen verlangen ihn. Ein fehlender oder unbekannter Schlüssel ergibt 401.

Schlüssel erstellen und widerrufen Sie auf Ihrer Profilseite. Bis zu 3 sind möglich.

Bewahren Sie den Schlüssel auf einem Server auf. Code im Browser legt ihn offen.

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

Antwort401application/json

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

Ratenlimits

Jeder Schlüssel erlaubt 10 Anfragen pro Minute und 100 pro Tag. Der Tageszähler wird um Mitternacht UTC zurückgesetzt.

Die offenen Datensätze brauchen keinen Schlüssel und erlauben 10 Anfragen pro Minute je IP-Adresse. Über einem Limit antwortet die API mit 429 und Retry-After.

Header	Beschreibung
`X-RateLimit-Limit`	Erlaubte Anfragen pro Tag
`X-RateLimit-Remaining`	Verbleibende Anfragen heute
`X-RateLimit-Limit-Minute`	Erlaubte Anfragen pro Minute
`X-RateLimit-Remaining-Minute`	Verbleibende Anfragen in dieser Minute
`Retry-After`	Wartezeit in Sekunden, mit einer 429 gesendet

Antwort429application/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"
  }
}

Fehler

Fehler nutzen HTTP-Statuscodes und einen JSON-Body mit einem festen Code und einer lesbaren Meldung. Werten Sie den Code aus, nicht die Meldung.

Status	Code	Beschreibung
401	`invalid_api_key`	Der Header X-API-Key fehlt, ist fehlerhaft oder unbekannt.
403	`key_disabled`	Der Schlüssel wurde deaktiviert.
404	`not_found`	Kein Verein, Spieler oder keine Saison passt zum Pfad.
422	`validation_error`	Ein Parameter hat den falschen Typ oder liegt außerhalb des Bereichs.
422	`invalid_date`	Ein Datum ist nicht JJJJ-MM-TT oder liegt in der Zukunft.
422	`invalid_season`	Die Saison sind keine zwei aufeinanderfolgenden Jahre wie 2025-2026.
422	`filter_required`	Spiele brauchen mindestens competition, season oder club.
429	`rate_limited`	Ein Ratenlimit ist erreicht. Warten Sie die Sekunden aus Retry-After ab.
503	`service_busy`	Eine frühere Tabelle wird gerade berechnet. Versuchen Sie es gleich erneut.

Antwort422application/json

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

Lizenz und Namensnennung

Die Daten stehen unter CC BY 4.0. Sie dürfen sie teilen und bearbeiten, auch kommerziell, wenn Sie beyondELO nennen, auf die Lizenz verlinken und Änderungen angeben. Verwenden Sie diese Namensnennung:

Lizenz lesen

beyondELO (https://beyondelo.com)

Offene Datensätze

CSV-Dateien ohne Schlüssel. Jede wird eine Stunde zwischengespeichert und trägt die Lizenz CC BY 4.0 im Link-Header.

Datensätze auflisten

GET/v1/datasets

Die CSV-Downloads mit ihren Spalten und dem Datum der letzten Aktualisierung.

Ohne Schlüssel

Parameter

Keine Parameter.

Fehler

429rate_limited

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

Antwort200application/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)"
  }
}

Vereinswertungen als CSV

GET/v1/datasets/club-ratings.csv

Jeder bewertete UEFA-Verein mit Wertung, Rang und Rang im eigenen Land, aus dem stündlichen Schnappschuss.

Ohne Schlüssel

Parameter

Keine Parameter.

Fehler

429rate_limited

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

Antwort200text/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

Spielerwertungen als CSV

GET/v1/datasets/player-ratings.csv

Jeder gelistete Spieler, der beste zuerst. Gelesen aus Live-Daten: Ändert sich ein Rang während des Downloads, kann eine Zeile doppelt vorkommen oder fehlen.

Ohne Schlüssel

Parameter

Keine Parameter.

Fehler

429rate_limited

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

Antwort200text/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

Vereinsverlauf als CSV

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

Jede in einer Saison erfasste Vereinswertung, nach Datum und dann nach Verein sortiert.

Ohne Schlüssel

Parameter

Parameter	Typ	Beschreibung
`season`erforderlich	string	Saison als zwei aufeinanderfolgende Jahre, zum Beispiel 2025-2026.

Fehler

404not_found
422invalid_season
429rate_limited

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

Antwort200text/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

Vereine

Vereine auflisten

GET/v1/clubs

Bewertete UEFA-Vereine, der beste zuerst: gelistete Vereine nach Rang, dann die übrigen nach Wertung. rd ist die Wertungsabweichung, hfa der Heimvorteil des Vereins, beide in Punkten.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`country`	string	Ländername oder -code, zum Beispiel England oder ENG.
`ranked`	boolean	true nur für gelistete Vereine, false nur für die übrigen.
`page`	integer	Seitennummer, ab 1.Standard 1
`per_page`	integer	Zeilen pro Seite, höchstens 1000.Standard 100

Fehler

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"

Antwort200application/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
  }
}

Einen Verein abrufen

GET/v1/clubs/{slug}

Ein Verein mit aktueller Wertung und aktuellem Rang.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`slug`erforderlich	string	Der Slug des Vereins, wie in seiner Adresse auf beyondelo.com.

Fehler

401invalid_api_key
403key_disabled
429rate_limited
404not_found

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

Antwort200application/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"
  }
}

Wertungsverlauf eines Vereins

GET/v1/clubs/{slug}/history

Die Wertung eines Vereins nach jedem Spiel, die älteste zuerst.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`slug`erforderlich	string	Der Slug des Vereins, wie in seiner Adresse auf beyondelo.com.
`from`	date	Erstes eingeschlossenes Datum, JJJJ-MM-TT.
`to`	date	Letztes eingeschlossenes Datum, JJJJ-MM-TT.
`page`	integer	Seitennummer, ab 1.Standard 1
`per_page`	integer	Zeilen pro Seite, höchstens 1000.Standard 1000

Fehler

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"

Antwort200application/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
  }
}

Ranglisten

Vereinsrangliste

GET/v1/rankings/clubs

Die gelisteten Vereine an einem Datum, der beste zuerst. Ohne Datum erhalten Sie die heutige Tabelle.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`date`	date	Die Tabelle an diesem Datum, JJJJ-MM-TT. Standard ist heute; künftige Daten werden abgelehnt.

Fehler

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"

Antwort200application/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
  }
}

Spieler

Spieler auflisten

GET/v1/players

Gelistete Spieler, der beste zuerst.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`country`	string	Nationalität, als Name oder Code.
`club`	string	Nur Spieler des Vereins mit diesem Slug.
`page`	integer	Seitennummer, ab 1.Standard 1
`per_page`	integer	Zeilen pro Seite, höchstens 1000.Standard 100

Fehler

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"

Antwort200application/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
  }
}

Einen Spieler abrufen

GET/v1/players/{slug}

Ein Spieler mit aktueller Wertung und aktuellem Rang. Nicht gelistete Spieler haben rank null.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`slug`erforderlich	string	Der Slug des Spielers, wie in seiner Adresse auf beyondelo.com.

Fehler

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"

Antwort200application/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)"
  }
}

Wertungsverlauf eines Spielers

GET/v1/players/{slug}/history

Die Wertung eines Spielers nach jedem Spiel, die älteste zuerst.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`slug`erforderlich	string	Der Slug des Spielers, wie in seiner Adresse auf beyondelo.com.
`from`	date	Erstes eingeschlossenes Datum, JJJJ-MM-TT.
`to`	date	Letztes eingeschlossenes Datum, JJJJ-MM-TT.
`page`	integer	Seitennummer, ab 1.Standard 1
`per_page`	integer	Zeilen pro Seite, höchstens 1000.Standard 1000

Fehler

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"

Antwort200application/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
  }
}

Länder und Wettbewerbe

Länder auflisten

GET/v1/countries

Die UEFA-Länder mit bewerteten Vereinen, nach der Durchschnittswertung ihrer Vereine.

API-Schlüssel nötig

Parameter

Keine Parameter.

Fehler

401invalid_api_key
403key_disabled
429rate_limited

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

Antwort200application/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
  }
}

Wettbewerbe auflisten

GET/v1/competitions

Die bewerteten Wettbewerbe mit erster und letzter erfasster Saison. end_season ist null, solange ein Wettbewerb läuft.

API-Schlüssel nötig

Parameter

Keine Parameter.

Fehler

401invalid_api_key
403key_disabled
429rate_limited

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

Antwort200application/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
  }
}

Spiele

Spiele auflisten

GET/v1/matches

Beendete Spiele, das neueste zuerst, mit den Wertungen beider Vereine vorher und nachher. Geben Sie mindestens einen Filter an.

API-Schlüssel nötig

Parameter

Parameter	Typ	Beschreibung
`competition`	string	Wettbewerbscode, zum Beispiel ucl.
`season`	string	Saison als zwei aufeinanderfolgende Jahre, zum Beispiel 2025-2026.
`club`	string	Nur Spiele des Vereins mit diesem Slug.
`page`	integer	Seitennummer, ab 1.Standard 1
`per_page`	integer	Zeilen pro Seite, höchstens 1000.Standard 100

Fehler

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"

Antwort200application/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
  }
}