> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Football data model and ID formats

> How The Stats API organizes football entities, stable string IDs, seasons, groups, stages, and availability flags.

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`.

<Note>
  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.
</Note>