# The Stats API

## Docs

- [What is The Stats API? Football data overview](https://www.thestatsapi.com/docs/introduction.md): The Stats API covers competitions, seasons, standings, teams, players, matches, live data, heatmaps, timelines, xG shotmaps, and betting odds.
- [Authenticate with The Stats API](https://www.thestatsapi.com/docs/authentication.md): Every request to The Stats API requires a Bearer token. Learn how to get your API key and add it to your requests.
- [Get started with The Stats API](https://www.thestatsapi.com/docs/quickstart.md): Make your first authenticated API call, verify the service is healthy, and start fetching football data in under five minutes.
- [Football data model and ID formats](https://www.thestatsapi.com/docs/concepts/data-model.md): How The Stats API organizes football entities, stable string IDs, seasons, groups, stages, and availability flags.
- [Pagination in The Stats API](https://www.thestatsapi.com/docs/concepts/pagination.md): List endpoints return paginated results. Learn how to use page, per_page, the limit alias, and the meta object.
- [API error responses and status codes](https://www.thestatsapi.com/docs/concepts/errors.md): The Stats API returns consistent JSON error objects for failure cases. Learn the error format, status codes, and common coverage behaviors.
- [API Reference overview and base URL](https://www.thestatsapi.com/docs/api-reference/overview.md): The Stats API is a REST API for football data. All protected requests use the base URL https://api.thestatsapi.com/api and require Bearer token authentication.
- [GET /health](https://www.thestatsapi.com/docs/api-reference/health.md): API health check endpoint for The Stats API.
- [GET /football/competitions — list competitions](https://www.thestatsapi.com/docs/api-reference/competitions/list.md): Returns a paginated list of football competitions. Filter by country, type, or name to find competition IDs for use in subsequent queries.
- [GET /football/competitions/{competition_id}](https://www.thestatsapi.com/docs/api-reference/competitions/get.md): Retrieve details for a competition, including country, type, current season, teams, and data availability flags.
- [GET /football/competitions/{competition_id}/seasons](https://www.thestatsapi.com/docs/api-reference/competitions/seasons.md): List seasons for a competition, newest first.
- [GET /football/competitions/{competition_id}/seasons/{season_id}/groups](https://www.thestatsapi.com/docs/api-reference/competitions/groups.md): List group labels available for a competition season.
- [GET /football/competitions/{competition_id}/seasons/{season_id}/standings](https://www.thestatsapi.com/docs/api-reference/competitions/standings.md): Fetch standings rows for a competition season, optionally filtered by group.
- [GET /football/teams — list and filter teams](https://www.thestatsapi.com/docs/api-reference/teams/list.md): List all teams, with optional filters for competition, season, country, or a partial name search to narrow results.
- [GET /football/teams/{team_id}](https://www.thestatsapi.com/docs/api-reference/teams/get.md): Retrieve details for a team, including country, stadium fields, and current competition context.
- [GET /football/teams/{team_id}/players](https://www.thestatsapi.com/docs/api-reference/teams/players.md): Return a team's current squad with extended player profile fields.
- [GET /football/teams/{team_id}/stats](https://www.thestatsapi.com/docs/api-reference/teams/stats.md): Retrieve team statistics for a competition season, including stage/group filters and league-table summary fields.
- [GET /football/teams/{team_id}/standings](https://www.thestatsapi.com/docs/api-reference/teams/standings.md): List competitions and seasons where a team has standings data.
- [GET /football/matches — list and filter matches](https://www.thestatsapi.com/docs/api-reference/matches/list.md): Retrieve a paginated list of football matches. Filter by competition, season, team, date range, or status to find fixtures, results, and live games.
- [GET /football/matches/{match_id}](https://www.thestatsapi.com/docs/api-reference/matches/get.md): Retrieve match details including teams, competition, season, status, scores, kickoff, venue, referee, xG, odds, and live-odds availability.
- [GET /football/matches/{match_id}/referee](https://www.thestatsapi.com/docs/api-reference/matches/referee.md): Return the referee assigned to a match with career summary stats.
- [GET /football/matches/{match_id}/stats](https://www.thestatsapi.com/docs/api-reference/matches/stats.md): Retrieve aggregated team statistics for a match, grouped by overview, shots, attack, passes, duels, defending, goalkeeping, and xG.
- [GET /football/matches/{match_id}/player-stats](https://www.thestatsapi.com/docs/api-reference/matches/player-stats.md): Retrieve per-player match statistics, optionally filtered by player IDs.
- [GET /football/matches/{match_id}/live-stats](https://www.thestatsapi.com/docs/api-reference/matches/live-stats.md): Return in-progress match statistics and live score metadata.
- [GET /football/matches/{match_id}/lineups](https://www.thestatsapi.com/docs/api-reference/matches/lineups.md): Return confirmed match lineups, formations, starting XIs, and substitutes.
- [GET /football/matches/{match_id}/players/{player_id}/heatmap](https://www.thestatsapi.com/docs/api-reference/matches/player-heatmap.md): Return 0-100 pitch-coordinate heatmap points for one player in one match.
- [GET /football/matches/{match_id}/timeline](https://www.thestatsapi.com/docs/api-reference/matches/timeline.md): Return a chronological event timeline for goals, shots, cards, substitutions, VAR, periods, and other match events.
- [GET /football/matches/{match_id}/shotmap](https://www.thestatsapi.com/docs/api-reference/matches/shotmap.md): Retrieve every shot in a match with xG, coordinates, body part, situation, derived flags, and non-penalty xG summary.
- [GET /football/players — list and search players](https://www.thestatsapi.com/docs/api-reference/players/list.md): Retrieve a paginated list of football players. Filter by team, position, or name search, or fetch a specific set of players by ID.
- [GET /football/players/{player_id}](https://www.thestatsapi.com/docs/api-reference/players/get.md): Retrieve a player's profile including nationality, position, date of birth, height, and current team details.
- [GET /football/players/{player_id}/stats](https://www.thestatsapi.com/docs/api-reference/players/stats.md): Retrieve a player's competition-season statistics, with optional stage filtering.
- [GET /football/players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap](https://www.thestatsapi.com/docs/api-reference/players/season-heatmap.md): Return aggregated 0-100 pitch-coordinate heatmap points for a player in one competition season.
- [GET /football/matches/{match_id}/odds](https://www.thestatsapi.com/docs/api-reference/matches/odds.md): Retrieve prematch and historical odds for match result, BTTS, totals, corners, and Asian handicap markets.
- [GET /football/matches/{match_id}/odds/live](https://www.thestatsapi.com/docs/api-reference/matches/live-odds.md): Return in-play odds for a match across live match, totals, corners, and handicap markets.
- [GET /football/matches/{match_id}/odds/players](https://www.thestatsapi.com/docs/api-reference/matches/player-odds.md): Return player-prop odds for a match, grouped by market and bookmaker.

## OpenAPI Specs

- [openapi](https://www.thestatsapi.com/docs/api-reference/openapi.json)