Find competition, team, player and match IDs

Use this page to find the IDs that every other endpoint needs.

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

Prompt

Using TheStatsAPI (reference: https://api.thestatsapi.com/llms.txt), write a server-side function that looks up the team_id for Arsenal's men's team and the current Premier League season_id, then prints both.

How IDs work

IDs are strings with a prefix that tells you what they point to. You look them up by name with the requests below, then pass them to other endpoints.

Prefix	What it is	Example
`comp_`	Competition	`comp_3039` (Premier League)
`sn_`	Season of a competition	`sn_8406098` (Premier League 26/27)
`tm_`	Team	`tm_9145` (Arsenal)
`pl_`	Player	`pl_45126714` (Bukayo Saka)
`mt_`	Match	`mt_200199332` (Arsenal v Leeds United)

Just need one ID? Use the ID finder in your dashboard (you need to be logged in).

The JavaScript examples run on your server and read your key from the THESTATSAPI_API_KEY environment variable.

Find a competition

Search by name. The best match comes first. Add sort=name if you want A to Z instead.

curl "https://api.thestatsapi.com/api/football/competitions?search=Premier&per_page=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/competitions?search=Premier&per_page=3",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
console.log(data[0].id); // "comp_3039"

Response (trimmed):

Response

{
  "data": [
    {
      "id": "comp_3039",
      "name": "Premier League",
      "country": "England",
      "country_code": "GB",
      "subdivision_code": "GB-ENG",
      "type": "league",
      "odds_available": true,
      "xg_available": true
    },
    {
      "id": "comp_84287",
      "name": "Egyptian Premier League",
      "country": "Egypt",
      "country_code": "EG",
      "type": "league"
    }
  ],
  "meta": { "page": 1, "per_page": 3, "total": 11, "total_pages": 4 }
}

You can also filter instead of searching:

country_code=GB-ENG&type=league lists English leagues. GB returns every UK nation; GB-ENG, GB-SCT, GB-WLS and GB-NIR return one. Other countries use codes such as DE or ES.
country=Spain matches the country name.

Find the current season and past seasons

Fetch the competition to get current_season_id.

curl "https://api.thestatsapi.com/api/football/competitions/comp_3039" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/competitions/comp_3039",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
console.log(data.current_season_id); // "sn_8406098"

Response

{
  "data": {
    "id": "comp_3039",
    "name": "Premier League",
    "type": "league",
    "has_team_stats": true,
    "has_player_stats": true,
    "odds_available": true,
    "xg_available": true,
    "current_season_id": "sn_8406098",
    "total_teams": 20
  }
}

For older seasons, list them. They come back newest first, and the current one has is_current: true.

curl "https://api.thestatsapi.com/api/football/competitions/comp_3039/seasons" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/competitions/comp_3039/seasons",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
const lastSeason = data.find((s) => s.year === "25/26");

Response

{
  "data": [
    { "id": "sn_8406098", "name": "Premier League 26/27", "year": "26/27", "start_year": 2026, "end_year": 2027, "is_current": true },
    { "id": "sn_6125938", "name": "Premier League 25/26", "year": "25/26", "start_year": 2025, "end_year": 2026, "is_current": false }
  ]
}

A season ID belongs to one competition. If you send a season_id with a different competition_id, you get a 400 error: “season_id does not belong to competition_id”.

Find a team (men’s or women’s)

Search by name. A club’s men’s and women’s teams often share a name, so check is_mens_team.

curl "https://api.thestatsapi.com/api/football/teams?search=Arsenal&per_page=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/teams?search=Arsenal&per_page=5",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();

Response (trimmed):

Response

{
  "data": [
    {
      "id": "tm_9145",
      "name": "Arsenal",
      "country": "England",
      "is_mens_team": true,
      "primary_competition": { "id": "comp_3039", "name": "Premier League" }
    },
    {
      "id": "tm_515555",
      "name": "Arsenal",
      "country": "England",
      "is_mens_team": false,
      "primary_competition": { "id": "comp_08207", "name": "Women's Super League" }
    },
    {
      "id": "tm_033813",
      "name": "Arsenal U21",
      "country": "England",
      "is_mens_team": true,
      "primary_competition": { "id": "comp_0488", "name": "Football League Trophy" }
    }
  ],
  "meta": { "page": 1, "per_page": 5, "total": 15, "total_pages": 3 }
}

To get one side only, add is_mens_team=true (men) or is_mens_team=false (women). On a team, is_mens_team is null when it isn’t known.

curl "https://api.thestatsapi.com/api/football/teams?search=Arsenal&is_mens_team=true&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

To list every team in a season, filter by competition and season instead: /football/teams?competition_id=comp_3039&season_id=sn_8406098 returns the 20 Premier League teams.

Find a player

Search needs at least 3 characters. It ignores case and accents, so odegaard finds “Ødegaard”.

curl "https://api.thestatsapi.com/api/football/players?search=saka&per_page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/players?search=saka&per_page=2",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
console.log(data[0].id); // "pl_45126714"

Response (trimmed):

Response

{
  "data": [
    {
      "id": "pl_45126714",
      "name": "Bukayo Saka",
      "position": "F",
      "date_of_birth": "2001-09-05",
      "nationality": "England",
      "current_team": { "id": "tm_9145", "name": "Arsenal", "jersey_number": 7 }
    }
  ],
  "meta": { "page": 1, "per_page": 2, "total": 157, "total_pages": 79 }
}

Other ways to find players:

/football/players?team_id=tm_9145 lists a team’s current players. Add position=F (or G, D, M) to narrow it.
/football/teams/tm_9145/players returns the squad with extra profile fields.
/football/players?player_ids=pl_45126714,pl_29627593 fetches several players in one call.

Find a match

Match IDs come from /football/matches. Filter by team, competition, season, date or status. For example, a team’s next fixture:

curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Fixtures and results for every filter.

Get started

Guides

Core concepts

Find competition, team, player and match IDs

How IDs work

Find a competition

Find the current season and past seasons

Find a team (men’s or women’s)

Find a player

Find a match

API reference

​How IDs work

​Find a competition

​Find the current season and past seasons

​Find a team (men’s or women’s)

​Find a player

​Find a match

​API reference

How IDs work

Find a competition

Find the current season and past seasons

Find a team (men’s or women’s)

Find a player

Find a match

API reference