Autenticación

Cada petición requiere una clave API. Pásela como cabecera (header) o como parámetro de consulta (query parameter).

# Cabecera (recomendado)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.leaguespy.com/v2/fixtures/updates"

# Parámetro de consulta
curl "https://api.leaguespy.com/v2/fixtures/updates?api_key=YOUR_KEY"

Niveles

Cada clave API está vinculada a un nivel (tier). Su nivel determina la actualidad de los datos, la frecuencia de actualización y la visibilidad de los campos.

Listar actualizaciones de partidos

Devuelve vistas previas de la alineación ordenadas por actualización más reciente. Incluye el XI predicho, banquillo, jugadores ausentes y alineaciones confirmadas cuando están disponibles.

Parámetros de consulta

Ejemplo de petición

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.leaguespy.com/v2/fixtures/updates?league_id=lg_xyz789&limit=5"

Respuesta

{
  "data": [
    {
      "fixture_id": "VJfWANbE",
      "home_team_id": "11uGdbIt",
      "home_team_name": "Levante",
      "home_team_name_en": "Levante",
      "home_team_logo": "https://img.leaguespy.com/teams/11uGdbIt.png",
      "away_team_id": "aGpkiedc",
      "away_team_name": "Athletic Club",
      "away_team_name_en": "Athletic Club",
      "away_team_logo": "https://img.leaguespy.com/teams/aGpkiedc.png",
      "league_id": "QBIQ7xJS",
      "league_name": "La Liga",
      "league_name_en": "La Liga",
      "league_logo": "https://img.leaguespy.com/leagues/QBIQ7xJS.png",
      "country_name": "Spain",
      "country_name_en": "Spain",
      "season_id": "n82fEZtc",
      "season_name": "2026/2027",
      "starting_at": "2026-10-21T18:00:00Z",
      "status": "scheduled",
      "home_score": null,
      "away_score": null,
      "updated_at": "2026-10-21T09:16:54.882613Z",
      "lineup": {
        "home": {
          "formation": "4-1-4-1",
          "is_confirmed": false,
          "is_nomination_announced": false,
          "starting_xi": [
            {
              "name": "Ryan M.",
              "name_en": "Ryan M.",
              "player_id": "BFKC5XyX",
              "squad_role": "regular",
              "detailed_position": "Goalkeeper",
              "formation_position": 1,
              "start_xi_probability": 99,
              "bench_probability": 0,
              "expected_minutes": 90,
              "expected_sub_off_probability": 0,
              "expected_sub_off_minute": null
            },
            {
              "name": "Ratkov P.",
              "name_en": "Ratkov P.",
              "player_id": "jzHpyPj5",
              "squad_role": "backup",
              "detailed_position": "Centre Forward",
              "formation_position": 11,
              "start_xi_probability": 10,
              "bench_probability": 40,
              "expected_minutes": 60.0,
              "expected_sub_off_probability": 100,
              "expected_sub_off_minute": 60
            }
          ],
          "bench": [
            {
              "name": "Axel Tape",
              "name_en": "Axel Tape",
              "player_id": "W10cOGaz",
              "squad_role": "youth",
              "detailed_position": "Right Back",
              "start_xi_probability": 0,
              "bench_probability": 50,
              "expected_minutes": 0,
              "expected_sub_in_probability": 0,
              "expected_sub_in_minute": null
            }
          ],
          "missing": [
            {
              "name": "Primo A.",
              "name_en": "Primo A.",
              "player_id": "Y78HfNjW",
              "squad_role": null,
              "detailed_position": "Goalkeeper",
              "missing_type": "injury",
              "reason": "Shoulder Injury",
              "missed_in_row": 10,
              "days_missed": 157,
              "expected_return": {
                "from": "2026-11-29",
                "to": "2027-02-24"
              },
              "absence_impact": null
            },
            {
              "name": "Sotelo H.",
              "name_en": "Sotelo H.",
              "player_id": "oSwdFDDa",
              "squad_role": "backup",
              "detailed_position": "Central Midfield",
              "missing_type": "doubtful",
              "reason": "Knee Injury",
              "missed_in_row": 3,
              "days_missed": 31,
              "expected_return": null,
              "absence_impact": "low",
              "play_probability": 30,
              "start_xi_probability": 17
            }
          ],
          "new_arrivals": [],
          "returning": [
            {
              "name": "Marc Santos",
              "name_en": "Marc Santos",
              "player_id": "F1PnN5eB",
              "squad_role": "youth",
              "detailed_position": "Left Back",
              "games_missed": 2,
              "days_out": 8,
              "returning_to": "bench"
            }
          ],
          "positional_battles": [
            {
              "position": "Right Back",
              "formation_position": 2,
              "contenders": [
                {
                  "name": "Toljan J.",
                  "name_en": "Toljan J.",
                  "player_id": "0G8ozWJE",
                  "squad_role": "rotation",
                  "probability": 50
                },
                {
                  "name": "Nacho Pérez",
                  "name_en": "Nacho Pérez",
                  "player_id": "fIaRlrWZ",
                  "squad_role": "regular",
                  "probability": 50
                }
              ]
            }
          ],
          "lineup_changes": {
            "count": 4,
            "in": [
              {
                "name": "Toljan J.",
                "name_en": "Toljan J.",
                "player_id": "0G8ozWJE"
              },
              {
                "name": "Mandi A.",
                "name_en": "Mandi A.",
                "player_id": "6DY8rtL6"
              },
              {
                "name": "Olasagasti J. A.",
                "name_en": "Olasagasti J. A.",
                "player_id": "6dWOnhit"
              },
              {
                "name": "Ratkov P.",
                "name_en": "Ratkov P.",
                "player_id": "jzHpyPj5"
              }
            ],
            "out": [
              {
                "name": "Nacho Pérez",
                "name_en": "Nacho Pérez",
                "player_id": "fIaRlrWZ"
              },
              {
                "name": "Ifeanyi Ndukwe",
                "name_en": "Ifeanyi Ndukwe",
                "player_id": "c3gj48hd"
              },
              {
                "name": "Enzo Bardeli",
                "name_en": "Enzo Bardeli",
                "player_id": "RrdKtGfe"
              },
              {
                "name": "Thiago Fernández",
                "name_en": "Thiago Fernández",
                "player_id": "k2fmKhNO"
              }
            ]
          }
        }
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "next_cursor": null,
    "has_more": false,
    "tier": "realtime",
    "timezone": "UTC"
  },
  "rate_limit": {
    "remaining": 119,
    "limit": 120,
    "resets_in_seconds": 60
  },
  "subscription": {
    "plan": "LeagueSpy Realtime",
    "sport": "Football",
    "tier": "realtime"
  }
}

{
  "data": [
    {
      "fixture_id": "VJfWANbE",
      "home_team_id": "11uGdbIt",
      "home_team_name": "Levante",
      "home_team_name_en": "Levante",
      "home_team_logo": "https://img.leaguespy.com/teams/11uGdbIt.png",
      "away_team_id": "aGpkiedc",
      "away_team_name": "Athletic Club",
      "away_team_name_en": "Athletic Club",
      "away_team_logo": "https://img.leaguespy.com/teams/aGpkiedc.png",
      "league_id": "QBIQ7xJS",
      "league_name": "La Liga",
      "league_name_en": "La Liga",
      "league_logo": "https://img.leaguespy.com/leagues/QBIQ7xJS.png",
      "country_name": "Spain",
      "country_name_en": "Spain",
      "season_id": "n82fEZtc",
      "season_name": "2026/2027",
      "starting_at": "2026-10-21T18:00:00Z",
      "status": "scheduled",
      "home_score": null,
      "away_score": null,
      "updated_at": "2026-10-21T09:16:54.882613Z",
      "lineup": {
        "home": {
          "formation": "4-1-4-1",
          "is_confirmed": false,
          "is_nomination_announced": false,
          "starting_xi": [
            {
              "name": "Ryan M.",
              "name_en": "Ryan M.",
              "player_id": "BFKC5XyX",
              "formation_position": 1
            },
            {
              "name": "Ratkov P.",
              "name_en": "Ratkov P.",
              "player_id": "jzHpyPj5",
              "formation_position": 11
            }
          ],
          "bench": [
            {
              "name": "Axel Tape",
              "name_en": "Axel Tape",
              "player_id": "W10cOGaz"
            }
          ],
          "missing": [
            {
              "name": "Primo A.",
              "name_en": "Primo A.",
              "player_id": "Y78HfNjW",
              "missing_type": "injury",
              "reason": "Shoulder Injury"
            },
            {
              "name": "Sotelo H.",
              "name_en": "Sotelo H.",
              "player_id": "oSwdFDDa",
              "missing_type": "doubtful",
              "reason": "Knee Injury"
            }
          ],
          "new_arrivals": [],
          "lineup_changes": {
            "count": 4,
            "in": [
              {
                "name": "Toljan J.",
                "name_en": "Toljan J.",
                "player_id": "0G8ozWJE"
              },
              {
                "name": "Mandi A.",
                "name_en": "Mandi A.",
                "player_id": "6DY8rtL6"
              },
              {
                "name": "Olasagasti J. A.",
                "name_en": "Olasagasti J. A.",
                "player_id": "6dWOnhit"
              },
              {
                "name": "Ratkov P.",
                "name_en": "Ratkov P.",
                "player_id": "jzHpyPj5"
              }
            ],
            "out": [
              {
                "name": "Nacho Pérez",
                "name_en": "Nacho Pérez",
                "player_id": "fIaRlrWZ"
              },
              {
                "name": "Ifeanyi Ndukwe",
                "name_en": "Ifeanyi Ndukwe",
                "player_id": "c3gj48hd"
              },
              {
                "name": "Enzo Bardeli",
                "name_en": "Enzo Bardeli",
                "player_id": "RrdKtGfe"
              },
              {
                "name": "Thiago Fernández",
                "name_en": "Thiago Fernández",
                "player_id": "k2fmKhNO"
              }
            ]
          }
        }
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "next_cursor": null,
    "has_more": false,
    "tier": "professional",
    "timezone": "UTC"
  },
  "rate_limit": {
    "remaining": 29,
    "limit": 30,
    "resets_in_seconds": 60
  },
  "subscription": {
    "plan": "LeagueSpy Professional",
    "sport": "Football",
    "tier": "professional"
  }
}

Obtener partido individual

Devuelve datos de alineación de un único partido por su ID público. La respuesta tiene la misma estructura que un elemento de la matriz data de arriba, con rate_limit y subscription en el nivel superior.

Parámetro de ruta

Ejemplo

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.leaguespy.com/v2/fixtures/fx_a1b2c3"

Respuesta

Devuelve el objeto del partido envuelto en un objeto data, con rate_limit y subscription en el nivel superior.

{
  "data": {
    "fixture_id": "fx_a1b2c3",
    "home_team_name": "FC Barcelona",
    "away_team_name": "Real Madrid",
    "lineup": { /* ... */ }             // Same structure as list response
  },
  "rate_limit": { /* ... */ },
  "subscription": { /* ... */ }
}

Comprobación de estado

No requiere autenticación. Devuelve un objeto de estado simple.

{ "status": "ok" }

Objeto Fixture

Un elemento de data en /v2/fixtures/updates, y data de /v2/fixtures/{fixture_id}.

Objeto Lineup

Cada equipo, lineup.home y lineup.away.

Ciclo de vida

• Un partido aparece en /v2/fixtures/updates cuando existen datos de alineación, desde hasta 7 días antes del inicio, y permanece hasta 1 hora después (48 horas para partidos aplazados, interrumpidos, cancelados y similares).
• Primero llegan las alineaciones predichas y los ausentes, hasta 7 días antes del inicio (un equipo que juega dos veces en una semana tiene ambos partidos), cuando hay predicción para la competición. La predicción se actualiza con cada nueva información hasta la alineación oficial. Antes de la confirmación is_confirmed es false y starting_xi / bench contienen la predicción.
• La alineación oficial reemplaza la predicción en cuanto se publica, normalmente 40 a 60 minutos antes del inicio (unos 50 a 60 minutos en las grandes ligas europeas y competiciones UEFA de clubes). is_confirmed pasa a true y una predicción posterior nunca lo revierte. En algunos partidos de divisiones inferiores la alineación oficial llega poco antes del inicio.
• Cada cambio de datos de alineación, status o starting_at actualiza updated_at, por lo que el polling con updated_since los detecta todos.
• /v2/fixtures/{fixture_id} devuelve los partidos desde el inicio de su suscripción.

Objetos de jugador

Jugadores en starting_xi y bench.

starting_xi[]

bench[]

Objeto de jugador ausente

Jugadores en missing[]: ausentes o dudosos para este partido.

Objeto de nuevo fichaje

Jugadores en new_arrivals[]: llegaron recientemente al club y figuran en el XI o banquillo. Se muestran durante los 3 primeros partidos tras el traspaso.

Objeto de jugador que regresa

RT Jugadores en returning[]: en el XI o banquillo tras perderse los últimos partidos del equipo. Máximo 4 por equipo, primero las ausencias más largas.

Objeto de batalla por posición

RT Elementos de positional_battles[]: posiciones en las que el jugador del XI predicho no es una elección clara; un aspirante es un suplente de la misma posición cuyas titularidades recientes se acercan a las del titular sin superarlas. probability es la probabilidad de cada jugador de ser titular en este partido, así que la del titular incluye su puesto en el XI predicho y los aspirantes se reparten como mucho el resto (p. ej. 78 frente a 22).

Objeto de cambios de alineación

lineup_changes compara starting_xi con el once inicial del último partido terminado del equipo en cualquier competición. Se omiten los amistosos de clubes; en selecciones los amistosos cuentan. Antes de la confirmación usa el XI predicho y después el oficial. null si no hay un partido anterior con alineación completa, si el XI actual aún no está completo y después de que el equipo juegue otro partido, hasta que se actualice la comparación (como tarde el día del partido).

Estadísticas de temporada (league_stats)

Bloque opcional en jugadores de starting_xi[], bench[] y missing[], añadido con ?include=league_stats. Siempre se refiere a la liga nacional del jugador, también en partidos de copa e internacionales.

Localización

Añada ?lang=ko a cualquiera de los endpoints de fixtures, o pídanos que el coreano sea el idioma por defecto de su clave. Sin parámetro de idioma (o con ?lang=en) la respuesta es en inglés, salvo que su clave tenga un idioma por defecto. GET /v2/languages lista los idiomas disponibles.

Los nombres se traducen en su campo: equipos, ligas, países y jugadores (también dentro de league_stats), signed_from y to_team_country. Un nombre sin traducción se devuelve en inglés. El original en inglés está siempre al lado en *_en (home_team_name_en, name_en, …), en todas las respuestas, para cruzarlo con sus datos.

Los valores fijos nunca se traducen: detailed_position, positional_battles[].position y reason siempre van en inglés. Con un idioma, su traducción se añade en detailed_position_label, position_label y reason_label. Códigos como status, missing_type, squad_role, absence_impact y stage, IDs, números, fechas, formaciones y temporadas nunca se traducen.

Avisamos con antelación, por email y en el registro de cambios, de cualquier cambio de idioma o formato en los valores.

Retransmisiones (broadcasts)

Bloque opcional del partido, añadido con ?include=broadcasts: las emisoras conocidas del partido, una entrada por país. Inglaterra, Escocia, Gales e Irlanda del Norte aparecen juntas como United Kingdom. La información suele aparecer unos tres días antes del inicio; un array vacío significa que aún no se conoce ninguna emisora. Las emisoras pueden añadirse o cambiar sin que cambie updated_at; lea el bloque al mostrar el partido.

Meta, límite de tasa y suscripción

meta se incluye en toda respuesta de lista; rate_limit y subscription en todas las respuestas.

Listas de valores

status

Los partidos en postponed, suspended, interrupted, cancelled, abandoned o awarded permanecen en /v2/fixtures/updates 48 horas tras el inicio. Un cambio de estado u hora de inicio actualiza updated_at.

missing_type

absence_impact

squad_role

new_arrivals[].stage

returning[].returning_to

Motivos de ausencia (reason)

reason siempre proviene de esta lista o de una de las plantillas de traspaso. Con ?lang=ko se devuelve en coreano (columna derecha).

Plantillas de traspaso

Transfer to <club> (<country>), Transfer/loan to <club> (<country>), Loan ended (returned to <club> (<country>))

Posiciones

Valores de detailed_position y positional_battles[].position. Defender, Midfielder y Attacker aparecen cuando sólo se conoce la línea.

formation_position

1 es el portero; luego cada línea de defensa a ataque, leída de derecha a izquierda desde la vista del equipo. Ejemplo 4-3-3: 1 POR, 2–5 defensa (2 lateral derecho … 5 lateral izquierdo), 6–8 medio, 9–11 delanteros.

formation

De defensa a ataque, sin contar el portero, p. ej. 4-2-3-1, 4-3-3, 4-4-2, 3-4-2-1, 4-1-4-1, 3-4-3, 3-5-2, 5-4-1, 5-3-2, 3-4-1-2, 3-1-4-2, 4-3-1-2, 4-1-3-2, 4-4-1-1, 4-2-2-2, 4-5-1.

Códigos de exact_position

GK, RB, RCB, CB, LCB, LB, RWB, LWB, RDM, DM, LDM, RCM, CM, LCM, RM, LM, RAM, AM, LAM, RW, LW, CF, ST.

Probabilidades y minutos

Todas las probabilidades son porcentajes enteros, 0 a 100 (start_xi_probability y bench_probability con máximo 99). En una alineación oficial los titulares tienen start_xi_probability: 99 y los suplentes 0. Los minutos van de 1 a 89; null significa no esperado (probabilidad menor al 25 %).

Null, vacío y ausente

Un array vacío [] significa que no se conoce nada, no es un error. null significa desconocido. Los indicadores (was_doubtful, debut) sólo aparecen cuando son true. Pueden añadirse claves nuevas; ignore las desconocidas.

Códigos de error

Todos los errores devuelven un cuerpo JSON con error_code y detail. Los errores de límite de tasa también incluyen retry_after.

{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "detail": "Rate limit exceeded. Please wait before making more requests.",
  "retry_after": 60
}

Cabeceras de respuesta

Incluidas en cada respuesta.

Sincronización inicial de datos

Las nuevas integraciones deben seguir este enfoque en dos fases para construir y mantener su dataset local:

# Fase 1: Descarga completa del dataset (una vez)
# Use paginación por offset sin updated_since
all_fixtures = []
offset = 0
sync_started_at = datetime.now(timezone.utc).isoformat()

while True:
    resp = httpx.get(API_URL, headers=headers, timeout=30,
                     params={"limit": 100, "offset": offset})
    page = resp.json()
    all_fixtures.extend(page["data"])

    if not page["meta"]["has_more"]:
        break
    offset += page["meta"]["limit"]

# Fase 2: Actualizaciones incrementales (continuas)
# Cambie a updated_since + cursor
last_check = sync_started_at

while True:
    params = {"limit": 100, "updated_since": last_check}
    cursor = None

    while True:
        if cursor:
            params["cursor"] = cursor
        resp = httpx.get(API_URL, headers=headers, params=params, timeout=30)
        data = resp.json()

        for fixture in data["data"]:
            upsert_fixture(fixture)  # Su lógica de upsert

        if not data["meta"]["has_more"]:
            break
        cursor = data["meta"]["next_cursor"]

    last_check = datetime.now(timezone.utc).isoformat()
    time.sleep(300)  # Poll cada 5 minutos

Paginación por cursor

Al consultar actualizaciones usando updated_since, use paginación basada en cursor en lugar de offset. La paginación por cursor garantiza la consistencia de datos — no perderá registros ni recibirá duplicados, incluso cuando los datos cambian entre peticiones de página.

Cómo funciona

Cada respuesta incluye un campo next_cursor en el objeto meta. Pase este valor como parámetro de consulta cursor en su siguiente petición para continuar exactamente donde lo dejó.

Ejemplo: consulta multi-página

# 1. Primera petición — empiece con updated_since, sin cursor
GET /v2/fixtures/updates?updated_since=2026-06-05T08:00:00Z&limit=50

# Respuesta:
{
  "data": [...50 partidos...],
  "meta": {
    "next_cursor": "eyJ1Ijoi...abc.d4e5f6",
    "has_more": true,
    "total": null
  }
}

# 2. Siguiente página — pase el cursor de la respuesta anterior
GET /v2/fixtures/updates?updated_since=2026-06-05T08:00:00Z&limit=50&cursor=eyJ1Ijoi...abc.d4e5f6

# 3. Última página — no hay más datos
{
  "data": [...12 partidos...],
  "meta": {
    "next_cursor": null,
    "has_more": false
  }
}

Estrategia de polling

Use polling basado en cursor con updated_since para obtener eficientemente solo los cambios desde su última sincronización.

import httpx
import time
from datetime import datetime, timezone

API_URL = "https://api.leaguespy.com/v2/fixtures/updates"
headers = {"X-API-Key": "YOUR_KEY"}
last_check = datetime.now(timezone.utc).isoformat()

while True:
    params = {"limit": 100, "updated_since": last_check}
    cursor = None

    while True:  # Recorra todas las páginas de resultados
        if cursor:
            params["cursor"] = cursor
        resp = httpx.get(API_URL, headers=headers, params=params, timeout=30)
        data = resp.json()

        for fixture in data["data"]:
            process_fixture(fixture)

        if not data["meta"]["has_more"]:
            break
        cursor = data["meta"]["next_cursor"]

    last_check = datetime.now(timezone.utc).isoformat()
    time.sleep(300)  # Poll cada 5 minutos

Registro de cambios