Data model and IDs

Use this page to understand how the API’s objects fit together before you write code.

Fastest way: ask your AI. Set up your coding tool once with Build with AI, then paste:

Read the API reference for TheStatsAPI at https://api.thestatsapi.com/llms.txt. Write TypeScript types for the Competition, Season, Team, Player and Match objects, using only the fields listed there. Mark nullable fields as nullable and keep every ID as a string.

How it fits together

Everything starts with a competition. A competition has seasons, and a season has matches. Teams and players appear in matches and in season stats.

Object	What it is	How to get it
Competition	A league, cup or tournament, such as the Premier League.	`GET /football/competitions?search=Premier`
Season	One edition of a competition, such as Premier League 26/27.	`GET /football/competitions/{competition_id}/seasons`
Match	One fixture in a season, with teams, status and score.	`GET /football/matches?competition_id=…&season_id=…`
Team	A club or national team.	`GET /football/teams?search=Arsenal`
Player	A person, with their current team.	`GET /football/players?search=saka`

What to send for common requests:

You want	Send
A league table	`competition_id` and `season_id` in the path of standings
A team’s season stats	`team_id` in the path, `season_id` in the query (team stats)
A player’s season stats	`player_id` in the path, `season_id` in the query, and optionally `competition_id` (player stats)
A team’s current squad	`team_id` (team players)

IDs

Every ID is a string with a prefix that tells you what it points to.

Prefix	Object	Example
`comp_`	Competition	`comp_3039` (Premier League)
`sn_`	Season	`sn_8406098` (Premier League 26/27)
`tm_`	Team	`tm_9145` (Arsenal men), `tm_515555` (Arsenal women)
`pl_`	Player	`pl_45126714` (Bukayo Saka)
`mt_`	Match	`mt_200199332` (Arsenal v Leeds United)
`ref_`	Referee	`ref_0890533` (Paul Tierney)
`mgr_`	Manager	`mgr_45779068` (Mikel Arteta)
`sh_`	Shot, in a shotmap	`sh_969103047`

Treat IDs as text. Keep the prefix and never convert them to numbers: some have leading zeros, such as tm_0256 (Leeds United). A malformed ID returns 400 BAD_REQUEST, for example Invalid match_id.

Not sure of an ID? See Find IDs.

Competitions

Field	Meaning
`id`, `name`	For example `comp_3039`, `Premier League`.
`type`	`league`, `cup` or `tournament`.
`country`, `country_code`	For example `England`, `GB`. Both are `null` for international competitions.
`subdivision_code`	The UK nation, such as `GB-ENG` (England) or `GB-SCT` (Scotland). `null` outside the UK.
`confederation`	For international competitions, such as `UEFA` or `FIFA`. `null` for domestic ones.
`current_season_id`	The latest season. Returned by Get a competition.
Availability flags	See Availability flags.

The country_code filter on /football/competitions accepts GB for all UK nations, or GB-ENG, GB-SCT, GB-WLS and GB-NIR for one nation. Other countries use ISO codes such as DE or ES.

Seasons

Field	Meaning
`id`, `name`	For example `sn_8406098`, `Premier League 26/27`.
`year`	Display label: `26/27` for seasons that span two years, `2026` for calendar-year seasons.
`start_year`, `end_year`	Numbers you can sort on, such as `2026` and `2027`.
`is_current`	`true` for the competition’s latest season.

Teams

Field	Meaning
`id`, `name`, `short_name`	For example `tm_9145`, `Arsenal`.
`country`	For example `England`.
`is_mens_team`	`true` for a men’s team, `false` for a women’s team, `null` when unknown.
`primary_competition`	The team’s main competition, as `{ id, name }`, or `null`.

A club’s men’s and women’s teams can share a name. Arsenal men are tm_9145 and Arsenal women are tm_515555. Use is_mens_team to tell them apart, or filter the list with GET /football/teams?search=Arsenal&is_mens_team=false.

Players

Field	Meaning
`id`, `name`, `first_name`, `last_name`	For example `pl_45126714`, `Bukayo Saka`.
`position`	`G`, `D`, `M`, `F`, or `""` when unknown.
`date_of_birth`, `age`	`YYYY-MM-DD` and whole years. `null` when unknown.
`nationality`, `height_cm`	`height_cm` is `null` when unknown.
`current_team`	`{ id, name, jersey_number }`. `jersey_number` is `null` when unknown.

Matches

Field	Meaning
`id`	For example `mt_200199332`.
`competition_id`, `season_id`	Where the match belongs.
`status`	`scheduled`, `live`, `finished`, `postponed` or `cancelled`.
`utc_date`	Kickoff time in UTC.
`matchday`	League round number. Can be `null` for cup and knockout fixtures.
`stage_name`	Named round for cup and knockout fixtures, such as `quarter_final` or `final`. `null` for regular league fixtures.
`group_label`	Group letter for group-stage matches in tournaments such as the World Cup, otherwise `null`.
`home_team`, `away_team`	`{ id, name }`.
`score`	`home` and `away` are normal-time goals. For extra time and penalties, read `after_extra_time`, `penalty_shootout` and `winner` (the overall winner).
`is_neutral`	`true` when neither team is at home. `null` means unknown, not `false`.
`live`	The in-play clock, on List matches only. `null` unless `status` is `live`.
`home_manager`, `away_manager`	`{ id, name }`, or `null` when not recorded.
Availability flags	See below.

Full field lists are on Get a match and List matches.

Availability flags

Some data is optional. Flags tell you whether it exists, so you can skip calls that would return nothing.

Flag	Found on	`true` means
`has_team_stats`	Competition	Team statistics exist for this competition.
`has_player_stats`	Competition	Player statistics exist for this competition.
`xg_available`	Competition, match	Expected goals (xG) data exists.
`shotmap_available`	Match	The shotmap has shots with xG values.
`xg_quality`	Match	`full` when shots carry per-shot xG, `none` when they don’t.
`odds_available`	Competition, match	Pre-match odds exist.
`live_odds_available`	Competition, match	In-play live odds are available.

Competition flags tell you whether a data type exists anywhere in that competition. They don’t tell you which seasons have it. For a season-by-season answer, use the coverage endpoints.

Dates and times

Kickoff times (utc_date) are ISO 8601 in UTC, for example 2026-10-10T11:30:00.000Z. Convert to local time in your app.
Filtering by day uses date_from and date_to in YYYY-MM-DD format. There is no date parameter. For one day, send the same date in both.
Local days: add utc_offset, such as -05:00, to read date_from and date_to in another time zone. Kickoff times in the response stay in UTC. In a URL, write a plus sign as %2B (utc_offset=%2B02:00), or build the query with URLSearchParams.
Birth dates (date_of_birth) are YYYY-MM-DD.

Null values

null means the value is unknown or doesn’t exist yet. It never means zero or false.

You see	It means
`score.home: null`	The match hasn’t been played.
`live: null`	The match isn’t live right now.
`matchday: null`	Usually a cup or knockout fixture. Read `stage_name` instead.
`is_neutral: null`	Unknown. Don’t assume a home advantage either way.
`height_cm: null`	Not recorded.

When optional data doesn’t exist for a match, some endpoints return 404 (for example Heatmap not available for this player in this match) and others return an empty data list. Check the availability flags first. See Errors.

Next steps

Find IDs: look up the IDs for your competitions, teams and players.
Data coverage: check which seasons have the data you need.
Pagination and sorting: fetch long lists in the right order.

Get started

Guides

Core concepts

How it fits together

IDs

Competitions

Seasons

Teams

Players

Matches

Availability flags

Dates and times

Null values

Next steps