跳到主要内容

API 参考

通过 HTTP 获取欧足联俱乐部和球员评分。CSV 下载无需密钥；JSON 接口需要一个免费密钥。所有数据采用 CC BY 4.0 许可。

登录以获取密钥在调试器中试用

简介

API 为只读，通过 HTTPS 返回 JSON。每个响应把内容放在 data 中，并附带一个包含许可和署名行的 meta 对象。

列表通过 page 和 per_page 分页，meta 中包含 total、page 和 per_page。评分列表还带有 as_of，即所依据榜单的日期。

基础 URL
https://public-api.beyondelo.com/v1
响应200application/json
{
  "data": {
    "status": "ok"
  },
  "meta": {
    "licence": "CC BY 4.0",
    "attribution": "beyondELO (https://beyondelo.com)"
  }
}

身份验证

在 X-API-Key 请求头中发送密钥。除开放数据集外，所有接口都需要它。缺少或未知的密钥返回 401。

在个人资料页面创建和撤销密钥，最多可持有 3 个。

请把密钥保存在服务器上。发送到浏览器的代码会暴露它。

curl "https://public-api.beyondelo.com/v1/clubs/arsenal" \
  -H "X-API-Key: $BEYONDELO_KEY"
响应401application/json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key"
  }
}

请求限制

每个密钥每分钟可发 10 次请求，每天 100 次。每日计数在 UTC 午夜重置。

开放数据集无需密钥，每个 IP 地址每分钟可发 10 次请求。超过任一限制时，API 返回 429 并附带 Retry-After。

响应头说明
X-RateLimit-Limit每天允许的请求数
X-RateLimit-Remaining今天剩余的请求数
X-RateLimit-Limit-Minute每分钟允许的请求数
X-RateLimit-Remaining-Minute本分钟剩余的请求数
Retry-After需等待的秒数，随 429 返回
响应429application/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"
  }
}

错误

错误使用 HTTP 状态码，并返回包含固定错误码和可读消息的 JSON。请根据错误码而非消息进行判断。

状态码错误码说明
401invalid_api_keyX-API-Key 请求头缺失、格式错误或未知。
403key_disabled该密钥已被停用。
404not_found没有与路径匹配的俱乐部、球员或赛季。
422validation_error某个参数类型错误或超出范围。
422invalid_date日期不是 YYYY-MM-DD 格式，或在未来。
422invalid_season赛季不是连续两年，例如 2025-2026。
422filter_required比赛查询至少需要 competition、season 或 club 之一。
429rate_limited已达到请求限制。请等待 Retry-After 指定的秒数。
503service_busy正在计算过去的排名，请稍后重试。
响应422application/json
{
  "error": {
    "code": "invalid_season",
    "message": "season must look like 2025-2026 (two consecutive years)"
  }
}

许可与署名

数据采用 CC BY 4.0 许可。只要注明 beyondELO、链接到许可并说明所做的修改，即可共享和改编，包括商业用途。请使用以下署名行：

阅读许可

beyondELO (https://beyondelo.com)

开放数据集

无需密钥的 CSV 文件。每个文件缓存一小时，并在 Link 响应头中注明 CC BY 4.0 许可。

列出数据集

GET/v1/datasets

CSV 下载列表，包括各自的列和最后更新日期。

无需密钥

参数

无参数。

错误

  • 429rate_limited
curl "https://public-api.beyondelo.com/v1/datasets"
响应200application/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

GET/v1/datasets/club-ratings.csv

每家已评分的欧足联俱乐部的评分、排名和国内排名，来自每小时快照。

无需密钥

参数

无参数。

错误

  • 429rate_limited
curl -o club-ratings.csv "https://public-api.beyondelo.com/v1/datasets/club-ratings.csv"
响应200text/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

GET/v1/datasets/player-ratings.csv

所有上榜球员，按评分从高到低。数据实时读取，下载期间排名变动可能导致某行重复或缺失。

无需密钥

参数

无参数。

错误

  • 429rate_limited
curl -o player-ratings.csv "https://public-api.beyondelo.com/v1/datasets/player-ratings.csv"
响应200text/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

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

一个赛季内记录的所有俱乐部评分，先按日期再按俱乐部排序。

无需密钥

参数

参数类型说明
season必填string以连续两年表示的赛季，例如 2025-2026。

错误

  • 404not_found
  • 422invalid_season
  • 429rate_limited
curl -o 2024-2025.csv "https://public-api.beyondelo.com/v1/datasets/club-elo-history/2024-2025.csv"
响应200text/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

俱乐部

列出俱乐部

GET/v1/clubs

已评分的欧足联俱乐部，从高到低：上榜俱乐部按排名，其余按评分。rd 是评分偏差，hfa 是俱乐部的主场优势，单位均为评分点。

需要 API 密钥

参数

参数类型说明
countrystring国家名称或代码，例如 England 或 ENG。
rankedbooleantrue 只返回上榜俱乐部，false 只返回未上榜俱乐部。
pageinteger页码，从 1 开始。默认 1
per_pageinteger每页行数，最多 1000。默认 100

错误

  • 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"
响应200application/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/v1/clubs/{slug}

单个俱乐部及其当前评分和排名。

需要 API 密钥

参数

参数类型说明
slug必填string俱乐部的 slug，与其 beyondelo.com 网址中的一致。

错误

  • 401invalid_api_key
  • 403key_disabled
  • 429rate_limited
  • 404not_found
curl "https://public-api.beyondelo.com/v1/clubs/arsenal" \
  -H "X-API-Key: $BEYONDELO_KEY"
响应200application/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"
  }
}

俱乐部评分历史

GET/v1/clubs/{slug}/history

俱乐部每场比赛后的评分，从最早开始。

需要 API 密钥

参数

参数类型说明
slug必填string俱乐部的 slug，与其 beyondelo.com 网址中的一致。
fromdate包含的第一个日期，YYYY-MM-DD。
todate包含的最后一个日期，YYYY-MM-DD。
pageinteger页码，从 1 开始。默认 1
per_pageinteger每页行数，最多 1000。默认 1000

错误

  • 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"
响应200application/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
  }
}

排名

俱乐部排名

GET/v1/rankings/clubs

某一日期的上榜俱乐部，从高到低。不传日期则返回今天的榜单。

需要 API 密钥

参数

参数类型说明
datedate该日期的榜单，YYYY-MM-DD。默认为今天；不接受未来日期。

错误

  • 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"
响应200application/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
  }
}

球员

列出球员

GET/v1/players

上榜球员，从高到低。

需要 API 密钥

参数

参数类型说明
countrystring国籍，名称或代码均可。
clubstring只返回该 slug 对应俱乐部的球员。
pageinteger页码，从 1 开始。默认 1
per_pageinteger每页行数，最多 1000。默认 100

错误

  • 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"
响应200application/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/v1/players/{slug}

单个球员及其当前评分和排名。未上榜球员的 rank 为 null。

需要 API 密钥

参数

参数类型说明
slug必填string球员的 slug，与其 beyondelo.com 网址中的一致。

错误

  • 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"
响应200application/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)"
  }
}

球员评分历史

GET/v1/players/{slug}/history

球员每场比赛后的评分，从最早开始。

需要 API 密钥

参数

参数类型说明
slug必填string球员的 slug，与其 beyondelo.com 网址中的一致。
fromdate包含的第一个日期，YYYY-MM-DD。
todate包含的最后一个日期，YYYY-MM-DD。
pageinteger页码，从 1 开始。默认 1
per_pageinteger每页行数，最多 1000。默认 1000

错误

  • 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"
响应200application/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
  }
}

国家和赛事

列出国家

GET/v1/countries

拥有已评分俱乐部的欧足联国家，按其俱乐部平均评分排序。

需要 API 密钥

参数

无参数。

错误

  • 401invalid_api_key
  • 403key_disabled
  • 429rate_limited
curl "https://public-api.beyondelo.com/v1/countries" \
  -H "X-API-Key: $BEYONDELO_KEY"
响应200application/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
  }
}

列出赛事

GET/v1/competitions

已评分的赛事，以及覆盖的第一个和最后一个赛季。赛事仍在进行时 end_season 为 null。

需要 API 密钥

参数

无参数。

错误

  • 401invalid_api_key
  • 403key_disabled
  • 429rate_limited
curl "https://public-api.beyondelo.com/v1/competitions" \
  -H "X-API-Key: $BEYONDELO_KEY"
响应200application/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
  }
}

比赛

列出比赛

GET/v1/matches

已结束的比赛，从最新开始，附双方赛前和赛后的评分。至少提供一个筛选条件。

需要 API 密钥

参数

参数类型说明
competitionstring赛事代码，例如 ucl。
seasonstring以连续两年表示的赛季，例如 2025-2026。
clubstring只返回该 slug 对应俱乐部参加的比赛。
pageinteger页码，从 1 开始。默认 1
per_pageinteger每页行数，最多 1000。默认 100

错误

  • 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"
响应200application/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
  }
}