Skip to main content

Concepts overview

Most of the API is built around four nouns. Get these right and the rest of the docs read in a single sitting.

Leagues​

A league is a competition with a stable identifier across seasons. Every match belongs to exactly one league.

  • A league has a country, a name, a current season and a sport.
  • Teams move between leagues (promotion / relegation) — leagues do not move.

Read more →

Matches​

A match is a fixture between two teams. Matches transition through a small state machine — scheduled → live → finished — though edge states like postponed, cancelled and abandoned exist too.

  • Matches carry scores, a status code, a period and (when live) a minute or game clock.
  • Matches are enriched with events (goals, cards…), statistics (possession, FG%…), lineups and a standings snapshot as they unfold.

Read more →

Status codes​

Every match has a numeric status_code. There are nine of them, covering the full lifecycle including penalty shoot-outs and abandonment.

See the full table →

Period codes​

The period field on a live match tells you which segment of the match is currently being played — first half, half time, third quarter, overtime…

The codes are sport-aware: 12 / 13 / 38 for football halves and half-time; 22 – 27 for basketball quarters and overtimes.

See the full table →

Time and timestamps​

Everything time-related is Unix epoch seconds in UTC unless explicitly noted. The updated_at field is the canonical "freshness" indicator — combine it with the live minute or game_clock to interpolate between polls if you need second-level precision.

Read more →

When in doubt, the API Reference is the authoritative schema for every field.