Football data model and ID formats

The Stats API organizes football data around stable entities: competitions, seasons, teams, players, matches, referees, shots, and odds. IDs are stable string values that can be reused across endpoints and API versions.

ID formats

Entity	ID prefix	Example
Competition	`comp_`	`comp_3039`
Season	`sn_`	`sn_6125938`
Team	`tm_`	`tm_0406`
Player	`pl_`	`pl_29627593`
Match	`mt_`	`mt_838955483`
Referee	`ref_`	`ref_7264609`
Shot	`sh_`	`sh_4812`

Relationships

Relationship	Description
Competition to seasons	Use `GET /football/competitions/{competition_id}/seasons` to find season IDs for a competition.
Competition season to groups	Tournament and cup seasons can expose group labels through `GET /football/competitions/{competition_id}/seasons/{season_id}/groups`.
Competition season to standings	Use the standings endpoint with optional `group` filters for grouped competitions.
Team to squad	Use `GET /football/teams/{team_id}/players` for the current squad.
Match to teams and players	Match records contain home/away team IDs; lineups, player stats, shotmaps, and heatmaps expose player-level detail.
Player to season stats	Player stats require a player, competition, and season, with optional stage filtering.

Competitions

Competition objects represent leagues, cups, and tournaments. They include geography and coverage flags.

Field	Type	Description
`id`	string	Stable competition ID, such as `comp_3039`.
`name`	string	Competition name.
`country`	string \| null	Country name. International competitions can be `null` and use `confederation`.
`country_code`	string \| null	ISO 3166 alpha-2 country code.
`subdivision_code`	string \| null	ISO 3166-2 subdivision code where applicable, such as `GB-ENG`.
`confederation`	string \| null	Confederation tag for international competitions.
`type`	string	`league`, `cup`, or `tournament`.
`has_team_stats`	boolean	Whether team stats are available.
`has_player_stats`	boolean	Whether player stats are available.
`odds_available`	boolean	Whether prematch or historical odds are available.
`live_odds_available`	boolean	Whether live odds are available for at least one match.
`xg_available`	boolean	Whether expected-goals data is available.

Matches

Match records carry schedule, score, team, competition, and coverage metadata.

Field	Type	Description
`id`	string	Stable match ID, such as `mt_838955483`.
`competition_id`	string	Competition ID.
`season_id`	string	Season ID.
`stage_name`	string \| null	Stage label when available, such as group stage or knockout phase.
`group_label`	string \| null	Group label for grouped tournaments.
`status`	string	Match status from the API contract.
`utc_date`	string	Kickoff time in UTC.
`home_team` / `away_team`	object	Team summary objects.
`score` / `final_score`	object \| null	Score data when available.
`xg_available`	boolean	Whether shotmap or xG data is available.
`odds_available`	boolean	Whether prematch/historical odds are available.
`live_odds_available`	boolean	Whether in-play odds are available.

Players and teams

Team and player IDs are shared across list, detail, statistics, lineup, heatmap, and odds endpoints. A team’s squad is available through the team players endpoint. Player season stats require competition_id and season_id because the same player can appear across multiple competitions and seasons.

Availability flags

Availability flags indicate whether optional datasets exist before you request them. Common flags include has_team_stats, has_player_stats, xg_available, odds_available, and live_odds_available.

Some endpoints return 404 when coverage is not available for a specific object, such as heatmaps before movement data exists or lineups before official team sheets are announced. Check each endpoint page for endpoint-specific behavior.

Get Started

Core Concepts

Football data model and ID formats

ID formats

Relationships

Competitions

Matches

Players and teams

Availability flags

​ID formats

​Relationships

​Competitions

​Matches

​Players and teams

​Availability flags

ID formats

Relationships

Competitions

Matches

Players and teams

Availability flags