Referencia de la API

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

Valoraciones de clubes y jugadores UEFA por HTTP. Las descargas CSV no necesitan clave; los endpoints JSON piden una gratuita. Todos los datos tienen licencia CC BY 4.0.

Inicia sesión para obtener una clave Probar en el explorador

Introducción

La API es de solo lectura y devuelve JSON por HTTPS. Cada respuesta pone su contenido en data y añade un objeto meta con la licencia y la línea de atribución.

Las listas se paginan con page y per_page, y meta incluye total, page y per_page. Las listas de valoraciones incluyen además as_of, la fecha de la tabla de la que proceden.

URL base

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

Respuesta200application/json

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

Autenticación

Envía tu clave en la cabecera X-API-Key. Todos los endpoints la necesitan salvo los conjuntos de datos abiertos. Una clave ausente o desconocida devuelve 401.

Crea y revoca claves en tu página de perfil. Puedes tener hasta 3.

Guarda la clave en un servidor. El código que llega al navegador la expone.

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

Respuesta401application/json

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

Límites de uso

Cada clave admite 10 peticiones por minuto y 100 al día. El contador diario se reinicia a medianoche UTC.

Los conjuntos de datos abiertos no necesitan clave y admiten 10 peticiones por minuto desde cada dirección IP. Al superar un límite, la API devuelve 429 con Retry-After.

Cabecera	Descripción
`X-RateLimit-Limit`	Peticiones permitidas al día
`X-RateLimit-Remaining`	Peticiones restantes hoy
`X-RateLimit-Limit-Minute`	Peticiones permitidas por minuto
`X-RateLimit-Remaining-Minute`	Peticiones restantes este minuto
`Retry-After`	Segundos de espera, enviado con un 429

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

Errores

Los errores usan códigos de estado HTTP y un cuerpo JSON con un código estable y un mensaje legible. Decide según el código, no según el mensaje.

Estado	Código	Descripción
401	`invalid_api_key`	La cabecera X-API-Key falta, está mal formada o es desconocida.
403	`key_disabled`	La clave ha sido desactivada.
404	`not_found`	Ningún club, jugador o temporada coincide con la ruta.
422	`validation_error`	Un parámetro tiene un tipo incorrecto o está fuera de rango.
422	`invalid_date`	Una fecha no es AAAA-MM-DD o está en el futuro.
422	`invalid_season`	La temporada no son dos años consecutivos, como 2025-2026.
422	`filter_required`	Los partidos necesitan al menos competition, season o club.
429	`rate_limited`	Se alcanzó un límite de uso. Espera los segundos de Retry-After.
503	`service_busy`	Se está calculando una clasificación pasada. Reinténtalo en breve.

Respuesta422application/json

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

Licencia y atribución

Los datos tienen licencia CC BY 4.0. Puedes compartirlos y adaptarlos, también con fines comerciales, si citas a beyondELO, enlazas la licencia e indicas qué cambiaste. Usa esta línea de atribución:

Leer la licencia

beyondELO (https://beyondelo.com)

Datos abiertos

Archivos CSV que no necesitan clave. Cada uno se guarda en caché una hora y lleva la licencia CC BY 4.0 en su cabecera Link.

Listar conjuntos de datos

GET/v1/datasets

Las descargas CSV, con sus columnas y la fecha de su última actualización.

Sin clave

Parámetros

Sin parámetros.

Errores

429rate_limited

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

Respuesta200application/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 de valoraciones de clubes

GET/v1/datasets/club-ratings.csv

Cada club UEFA valorado con su valoración, su puesto y su puesto en su país, según la instantánea horaria.

Sin clave

Parámetros

Sin parámetros.

Errores

429rate_limited

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

Respuesta200text/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 de valoraciones de jugadores

GET/v1/datasets/player-ratings.csv

Cada jugador clasificado, del mejor al peor. Se lee de datos en vivo: un cambio de puesto durante la descarga puede repetir u omitir una fila.

Sin clave

Parámetros

Sin parámetros.

Errores

429rate_limited

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

Respuesta200text/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 del historial de clubes

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

Cada valoración de club registrada en una temporada, ordenada por fecha y después por club.

Sin clave

Parámetros

Parámetro	Tipo	Descripción
`season`obligatorio	string	Temporada como dos años consecutivos, por ejemplo 2025-2026.

Errores

404not_found
422invalid_season
429rate_limited

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

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

Clubes

Listar clubes

GET/v1/clubs

Clubes UEFA valorados, del mejor al peor: los clasificados por puesto y luego el resto por valoración. rd es la desviación de la valoración y hfa la ventaja de local del club, ambas en puntos.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`country`	string	Nombre o código del país, por ejemplo England o ENG.
`ranked`	boolean	true solo para clubes clasificados, false solo para los no clasificados.
`page`	integer	Número de página, desde 1.Por defecto 1
`per_page`	integer	Filas por página, como máximo 1000.Por defecto 100

Errores

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"

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

Obtener un club

GET/v1/clubs/{slug}

Un club con su valoración y su puesto actuales.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`slug`obligatorio	string	El slug del club, como en su dirección de beyondelo.com.

Errores

401invalid_api_key
403key_disabled
429rate_limited
404not_found

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

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

Historial de un club

GET/v1/clubs/{slug}/history

La valoración de un club tras cada partido, de la más antigua a la más reciente.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`slug`obligatorio	string	El slug del club, como en su dirección de beyondelo.com.
`from`	date	Primera fecha incluida, AAAA-MM-DD.
`to`	date	Última fecha incluida, AAAA-MM-DD.
`page`	integer	Número de página, desde 1.Por defecto 1
`per_page`	integer	Filas por página, como máximo 1000.Por defecto 1000

Errores

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"

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

Clasificaciones

Clasificación de clubes

GET/v1/rankings/clubs

Los clubes clasificados en una fecha, del mejor al peor. Sin fecha obtienes la tabla de hoy.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`date`	date	La tabla en esta fecha, AAAA-MM-DD. Por defecto, hoy; las fechas futuras se rechazan.

Errores

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"

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

Jugadores

Listar jugadores

GET/v1/players

Jugadores clasificados, del mejor al peor.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`country`	string	Nacionalidad, por nombre o código.
`club`	string	Solo jugadores del club con este slug.
`page`	integer	Número de página, desde 1.Por defecto 1
`per_page`	integer	Filas por página, como máximo 1000.Por defecto 100

Errores

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"

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

Obtener un jugador

GET/v1/players/{slug}

Un jugador con su valoración y su puesto actuales. Los no clasificados tienen rank null.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`slug`obligatorio	string	El slug del jugador, como en su dirección de beyondelo.com.

Errores

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"

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

Historial de un jugador

GET/v1/players/{slug}/history

La valoración de un jugador tras cada partido, de la más antigua a la más reciente.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`slug`obligatorio	string	El slug del jugador, como en su dirección de beyondelo.com.
`from`	date	Primera fecha incluida, AAAA-MM-DD.
`to`	date	Última fecha incluida, AAAA-MM-DD.
`page`	integer	Número de página, desde 1.Por defecto 1
`per_page`	integer	Filas por página, como máximo 1000.Por defecto 1000

Errores

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"

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

Países y competiciones

Listar países

GET/v1/countries

Los países UEFA con clubes valorados, según la valoración media de sus clubes.

Necesita una clave

Parámetros

Sin parámetros.

Errores

401invalid_api_key
403key_disabled
429rate_limited

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

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

Listar competiciones

GET/v1/competitions

Las competiciones valoradas, con la primera y la última temporada cubiertas. end_season es null mientras la competición sigue en curso.

Necesita una clave

Parámetros

Sin parámetros.

Errores

401invalid_api_key
403key_disabled
429rate_limited

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

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

Partidos

Listar partidos

GET/v1/matches

Partidos terminados, del más reciente al más antiguo, con las valoraciones de ambos clubes antes y después. Indica al menos un filtro.

Necesita una clave

Parámetros

Parámetro	Tipo	Descripción
`competition`	string	Código de la competición, por ejemplo ucl.
`season`	string	Temporada como dos años consecutivos, por ejemplo 2025-2026.
`club`	string	Solo partidos jugados por el club con este slug.
`page`	integer	Número de página, desde 1.Por defecto 1
`per_page`	integer	Filas por página, como máximo 1000.Por defecto 100

Errores

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"

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