Introduction

This page explains what football data TheStatsAPI has and how its requests and responses work. The API is read-only: you send HTTPS GET requests with your API key and get JSON back.

Fastest way to build: give your AI coding tool https://api.thestatsapi.com/llms.txt and a starter prompt. See Build with AI.

What data you can get

Data	What you get	Start with
Competitions	Leagues, cups and international tournaments, with their seasons, groups and league tables	List competitions
Teams	Profiles, squads, season stats, standings history, injuries and suspensions	List teams
Players	Profiles, season stats, injuries and suspensions, season heatmaps	List players
Matches	Fixtures, results and live scores, with team and player stats, lineups, event timelines and referees	List matches
xG	Shot maps with xG for every shot, plus player heatmaps	Shotmap
Odds	Pre-match, in-play and player-prop odds from Bet365, Paddy Power, BetMGM UK, Pinnacle and Betfair Exchange, where available	Match odds
Coverage	Which competitions and seasons have which data types	Coverage by competition

Not every competition has every data type, and how far back the data goes varies by competition. Check Coverage before you build a feature. Competitions and matches also carry flags such as xg_available and odds_available, so you can tell before you call an endpoint.

Base URL and authentication

Every endpoint lives under this base URL:

https://api.thestatsapi.com/api

Send your API key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Get a key on the API keys page. See Authentication for details.

Requests

Filters are query parameters. For example, /football/matches?team_id=tm_9145&status=finished.
Only documented parameters are accepted. A misspelled or unknown parameter returns 400 UNKNOWN_PARAMETER. The message suggests the closest name and lists the parameters the endpoint accepts.
IDs are prefixed strings. Use them exactly as the API returns them.
Prefix Entity Example
comp_ Competition comp_3039 (Premier League)
sn_ Season sn_8406098 (Premier League 26/27)
tm_ Team tm_9145 (Arsenal)
pl_ Player pl_45126714 (Bukayo Saka)
mt_ Match mt_200199332
Dates are YYYY-MM-DD in date_from and date_to. There is no date parameter. Kickoff times in responses are UTC.

Prefix	Entity	Example
`comp_`	Competition	`comp_3039` (Premier League)
`sn_`	Season	`sn_8406098` (Premier League 26/27)
`tm_`	Team	`tm_9145` (Arsenal)
`pl_`	Player	`pl_45126714` (Bukayo Saka)
`mt_`	Match	`mt_200199332`

Responses

List endpoints return a data array and a meta object for paging. For example, GET /football/teams?search=Arsenal&is_mens_team=true&per_page=1 returns:

{
  "data": [
    {
      "id": "tm_9145",
      "name": "Arsenal",
      "short_name": "Arsenal",
      "country": "England",
      "is_mens_team": true,
      "primary_competition": { "id": "comp_3039", "name": "Premier League" }
    }
  ],
  "meta": { "page": 1, "per_page": 1, "total": 13, "total_pages": 13 }
}

Single-item endpoints return one object in data. For example, GET /football/competitions/comp_3039 returns (trimmed):

{
  "data": {
    "id": "comp_3039",
    "name": "Premier League",
    "country": "England",
    "type": "league",
    "xg_available": true,
    "current_season_id": "sn_8406098",
    "total_teams": 20
  }
}

Errors always use the same shape. Branch on code:

{
  "error": {
    "code": "UNKNOWN_PARAMETER",
    "message": "Unknown query parameter 'date' (did you mean 'date_from' or 'date_to'?). Supported parameters: ...",
    "status_code": 400
  }
}

Learn more in Pagination, Errors and Rate limits.

Data is pull-only. There are no webhooks or streaming connections. For live matches, poll the live endpoints. See Live matches.

Versioning and changes

We add new endpoints, parameters and response fields over time. Write code that ignores fields it doesn’t recognise.
Deprecated endpoints are labelled in the API reference. For example, player-prop odds moved to /v2/football/matches/{match_id}/odds/players, and the old v1 path is marked deprecated.

Get started

Guides

Core concepts

What data you can get

Base URL and authentication

Requests

Responses

Versioning and changes