Authentication

Every request requires an API key. Pass it as a header or query parameter.

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

# Query parameter
curl "https://api.leaguespy.com/v2/fixtures/updates?api_key=YOUR_KEY"

Tiers

Each API key is bound to a tier. Your tier determines data freshness, update frequency, and field visibility.

List fixture updates

Returns fixture lineup previews sorted by most recently updated. Includes predicted XI, bench, missing players, and confirmed lineups when available.

Query parameters

Example request

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

Response

{
  "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"
  }
}

Get single fixture

Returns lineup data for a single fixture by its public ID. Response is the same shape as one item from the data array above, with rate_limit and subscription at the top level.

Path parameter

Example

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

Response

Returns the fixture object wrapped in a data object, with rate_limit and subscription at the top level.

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

Health check

No authentication required. Returns a simple status object.

{ "status": "ok" }

Fixture object

One item of data in /v2/fixtures/updates, and data of /v2/fixtures/{fixture_id}.

Lineup object

Each side, lineup.home and lineup.away.

Data lifecycle

• A fixture appears in /v2/fixtures/updates once lineup data exists for it, from up to 7 days before kickoff, and stays until 1 hour after kickoff (48 hours for postponed, interrupted, cancelled and similar fixtures).
• Predicted lineups and missing players arrive first, up to 7 days before kickoff (a team that plays twice in a week has both matches), where a prediction is available for the competition. The prediction is updated with every new piece of information until the official lineup. Before confirmation is_confirmed is false and starting_xi / bench hold the prediction.
• The official lineup replaces the prediction as soon as it is published, usually 40 to 60 minutes before kickoff (about 50 to 60 minutes in the top European leagues and UEFA club competitions). is_confirmed switches to true and is never switched back by a later prediction. For some lower-division matches the official lineup arrives only shortly before kickoff.
• Every change of lineup data, status or starting_at updates updated_at, so polling with updated_since sees all of them.
• /v2/fixtures/{fixture_id} returns matches from the start of your subscription onwards.

Player objects

Players in starting_xi and bench.

starting_xi[]

bench[]

Missing player object

Players in missing[]: out or doubtful for this match.

New arrival object

Players in new_arrivals[]: joined the club recently and are named in this match's XI or bench. Listed for the first 3 matches after the move.

Returning player object

RT Players in returning[]: named in this match's XI or bench after missing the team's most recent match(es). At most 4 per team, longest absences first.

Positional battle object

RT Items of positional_battles[]: positions where the player in the predicted XI is not a clear choice — a challenger is a bench player at the same position whose starts in recent matches are close to, and not above, the starter's. probability is each player's chance to start this match, so the starter's counts his place in the predicted XI and the challengers share at most the rest (e.g. 78 vs 22).

Lineup changes object

lineup_changes compares starting_xi with the starting eleven of the team's previous finished match in any competition. Club friendlies are skipped; for national teams friendlies count. Before confirmation it uses the predicted XI, after confirmation the official one. null when there is no previous match with a complete lineup, when the current XI is not complete yet, and after the team plays another match, until the comparison is refreshed (at the latest on the day of the match).

Season statistics (league_stats)

Optional block on starting_xi[], bench[] and missing[] players, added with ?include=league_stats. Always refers to the player's domestic league, also for cup and international matches.

Localization

Add ?lang=ko to either fixtures endpoint, or ask us to set Korean as your key's default language. Without a language parameter (or with ?lang=en) the response is in English, unless your key has a default language. GET /v2/languages lists the available languages.

Names are translated in place: team, league, country and player names (also inside league_stats), signed_from and to_team_country. A name without a translation is returned in English. The English original is always available next to it in *_en (home_team_name_en, name_en, …), on every request, so you can match against your own data.

Fixed values are never translated: detailed_position, positional_battles[].position and reason always stay in English. With a language, their translation is added in detailed_position_label, position_label and reason_label. Codes such as status, missing_type, squad_role, absence_impact and stage, IDs, numbers, dates, formations and season labels are never translated.

We announce any change to the language or format of response values in advance, by email and in the changelog.

Broadcasts (broadcasts)

Optional block on the fixture, added with ?include=broadcasts: the broadcasters known for the match, one entry per country. England, Scotland, Wales and Northern Ireland are listed together as United Kingdom. Broadcast information usually appears about three days before kickoff; an empty array means no broadcaster is known yet. Broadcasters can be added or change without a change of updated_at, so read the block when you show the match.

Meta, rate limit & subscription

meta is part of every list response; rate_limit and subscription of every response.

Value lists

status

Fixtures in postponed, suspended, interrupted, cancelled, abandoned or awarded stay in /v2/fixtures/updates for 48 hours after kickoff. A status or kickoff change updates updated_at.

missing_type

absence_impact

squad_role

new_arrivals[].stage

returning[].returning_to

Absence reasons (reason)

reason always comes from this list or one of the transfer templates. With ?lang=ko it is returned in Korean (right column).

Transfer templates

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

Positions

Values of detailed_position and positional_battles[].position. Defender, Midfielder and Attacker appear when only the line is known.

formation_position

1 is the goalkeeper, then each line from defence to attack, each line read from right to left from the team's own view. Example 4-3-3: 1 GK, 2–5 back four (2 right back … 5 left back), 6–8 midfield, 9–11 forwards.

formation

Read from defence to attack, goalkeeper not counted, e.g. 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.

exact_position codes

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

Probabilities and minutes

All probabilities are whole percentages, 0 to 100 (start_xi_probability and bench_probability are capped at 99). In an official lineup starters have start_xi_probability: 99 and substitutes 0. Minute fields are 1 to 89; null means not expected (chance below 25 %).

Null, empty and absent

An empty array [] means nothing is known, not an error. null means not known. Flags (was_doubtful, debut) appear only when true. New keys may be added; clients should ignore unknown keys.

Error codes

All errors return a JSON body with error_code and detail. Rate limit errors also include retry_after.

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

Response headers

Included on every response.

Initial data sync

New integrations should follow this two-phase approach to build and maintain their local dataset:

# Phase 1: Full dataset download (one-time)
# Use offset pagination without 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"]

# Phase 2: Incremental updates (ongoing)
# Switch to 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)  # Your upsert logic

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

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

Cursor pagination

When polling for updates using updated_since, use cursor-based pagination instead of offset. Cursor pagination guarantees data consistency — you won't miss records or see duplicates, even when data changes between page requests.

How it works

Each response includes a next_cursor field in the meta object. Pass this value as the cursor query parameter in your next request to continue from exactly where you left off.

Example: multi-page fetch

# 1. First request — start with updated_since, no cursor
GET /v2/fixtures/updates?updated_since=2026-06-05T08:00:00Z&limit=50

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

# 2. Next page — pass the cursor from previous response
GET /v2/fixtures/updates?updated_since=2026-06-05T08:00:00Z&limit=50&cursor=eyJ1Ijoi...abc.d4e5f6

# 3. Last page — no more data
{
  "data": [...12 fixtures...],
  "meta": {
    "next_cursor": null,
    "has_more": false
  }
}

Polling strategy

Use cursor-based polling with updated_since to efficiently fetch only changes since your last sync.

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:  # Page through all results
        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 every 5 minutes

Pagination

When meta.total exceeds your limit, increment offset to fetch remaining pages.

import httpx

API_URL = "https://api.leaguespy.com/v2/fixtures/updates"
headers = {"X-API-Key": "YOUR_KEY"}

all_fixtures = []
offset = 0

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

    # Stop when we've fetched everything
    if offset + page["meta"]["limit"] >= page["meta"]["total"]:
        break
    offset += page["meta"]["limit"]

Changelog