Concepts

Fixture ids

A fixture id looks like nba-261025-mia-cha: league, local date (yymmdd), away and home team. A second game of the same teams on the same day (an MLB doubleheader) gets -2: mlb-260925-chc-bos-2.

Ids are opaque

Use the id as a key only; don't parse it. It is minted once and never changes, even when the game moves: its date part can then differ from the game's date. Read the league, date and teams from their fields.

Leagues

league	name	timezone
mlb	MLB	America/New_York
nba	NBA	America/New_York
nfl	NFL	America/New_York
cfb	NCAAF (Division I: every game with an FBS or FCS team)	America/New_York
nhl	NHL	America/New_York
epl	English Premier League	Europe/London
bund	Bundesliga	Europe/Berlin
laliga	LaLiga	Europe/Madrid
ucl	UEFA Champions League (league phase)	Europe/Berlin

Bundesliga clubs carry their official German names (FC Bayern München, 1. FC Köln) and the league's own abbreviations (FCB, KOE), LaLiga clubs LaLiga's short names and abbreviations (FC Barcelona BAR, Málaga CF MGA). Champions League clubs carry UEFA's names and codes (Liverpool FC LIV, FC Bayern München BAY); a club playing in both its league and the Champions League is a team of each, with its own id. Names are UTF-8; join on the fixture id or the team id, not on names.

Dates

All times are UTC, e.g. 2026-10-30T00:15:00.000Z. The date parameter is a local date in the league's timezone: an NFL game at 2026-10-30T00:15:00Z is played on the evening of 2026-10-29 in New York, so it is listed under date=2026-10-29. Without date, endpoints answer for today in the league's timezone.

Statuses

status	meaning
Scheduled	not started
Delayed	a delayed start was reported; it still starts on its date
In Progress	live; detail may say e.g. Delayed: Rain for an in-game delay, or Awaiting confirmation once ended but before the final score is confirmed
Suspended	started, halted, resumes later (e.g. an MLB suspended game); keeps its score and id. Also a soccer match abandoned during play (detail Abandoned, see Abandoned matches)
Final	finished, score confirmed
Postponed	will not be played on its date: bets are pushed. The rescheduled game is a new fixture
Cancelled	will not take place

detail carries the reason, e.g. Rain, or a break: Halftime, End of Period, Intermission (NHL). Two details have a fixed meaning: Not played (a Postponed match no postponement was announced for, see below) and Abandoned.

We never guess a status from the clock: a game stays Scheduled until it is reported started, and Delayed only when a delay is reported.

Postponements

A game's date locks 7 days before its start. Before that, a reschedule just updates date (TV picks, flexed games), and the id stays.

After the lock, a game that isn't played on its locked date is Postponed, and that fixture ends there. The rescheduled game becomes a new fixture, linked both ways:

{"id": "mlb-260402-tor-cws", "status": "Postponed", "replaced_by": "mlb-260403-tor-cws"}
{"id": "mlb-260403-tor-cws", "status": "Final", "replaces": "mlb-260402-tor-cws"}

replaced_by may come weeks later, once the new date is known (NBA and NHL games are often moved far out).

Bundesliga and LaLiga matches appear 7 days ahead, so their date is locked from the start. A match called off isn't always announced as postponed; it is still marked Postponed:

• taken off the schedule before kickoff, or moved to another date: within about 15 minutes on the match day, within about an hour on earlier days (detail Not played, or moved to the new date);
• otherwise at the latest the morning after its date (06:00 local time), with detail Not played.

original_date is the start as of the lock; date is the current (or actual) start.

Abandoned matches

A soccer match halted for good during play is Suspended with detail Abandoned. It keeps its score, leaves /live, and isn't graded until the league decides whether the result is awarded or the match replayed, which can take weeks. Should the match resume after all on the day, it goes back to In Progress.

Corrections

A final score corrected afterwards (rare) is updated in place and gets corrected_at. The status and id don't change.