Find any ID · Soccer Data docs

Almost every endpoint asks for an id: which competition, which season, which team. This guide shows how to find each one. You only need to do it once per thing, because ids never change and are safe to store.

All examples send your key in the X-Api-Key header. Keep that key in server-side code.

The kinds of id

Starts with	Points to	Example
`competition_`	A league, cup or tournament	`competition_705uv6jm8myn` (Premier League)
`season_`	One season of a competition	`season_hr1ie7yrsdmt` (Premier League 26/27)
`team_`	A club or national team	`team_f0ibhxdw7hs5` (Arsenal men)
`player_`	A player	`player_ul3vc6om97u5` (Bukayo Saka)
`match_`	A single match	`match_yoeml0e6ae37` (Arsenal v Leeds United)

Ids are strings. The word at the start tells you what kind of thing the id names, and the 12 characters after it identify which one. Data model lists a few more kinds, such as shots, managers and referees.

Competitions

Search by name. The closest match comes first; add sort=name if you'd rather have them A to Z.

curl "https://api.soccer-data.co/v1/competitions?search=Premier&per_page=3" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "competition_705uv6jm8myn",
      "name": "Premier League",
      "country": "England",
      "country_code": "GB",
      "subdivision_code": "GB-ENG",
      "type": "league",
      "xg_available": true
    }
  ],
  "meta": { "page": 1, "per_page": 3, "total": 6, "total_pages": 2 }
}

You can also filter instead of searching, for example country_code=GB-ENG&type=league for English leagues, or country=Spain for everything in Spain.

Seasons

To get the season that's running now, fetch the competition and read current_season_id:

curl "https://api.soccer-data.co/v1/competitions/competition_705uv6jm8myn" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "data": {
    "id": "competition_705uv6jm8myn",
    "name": "Premier League",
    "current_season_id": "season_hr1ie7yrsdmt"
  }
}

For older seasons, list them all. The newest comes first, and the current one has is_current: true.

curl "https://api.soccer-data.co/v1/competitions/competition_705uv6jm8myn/seasons" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "data": [
    { "id": "season_hr1ie7yrsdmt", "name": "Premier League 26/27", "year": "26/27", "is_current": true },
    { "id": "season_98l95mxugqs9", "name": "Premier League 25/26", "year": "25/26", "is_current": false }
  ]
}

Warning A season id belongs to one competition. If you pair it with a different competition_id, you get a 400 saying the season doesn't belong to that competition.

Teams

curl "https://api.soccer-data.co/v1/teams?search=Arsenal&per_page=5" \
  -H "X-Api-Key: YOUR_API_KEY"

A search like this can return several teams with the same name:

{
  "data": [
    {
      "id": "team_f0ibhxdw7hs5",
      "name": "Arsenal",
      "is_mens_team": true,
      "primary_competition": { "id": "competition_705uv6jm8myn", "name": "Premier League" }
    },
    {
      "id": "team_co5mh4glxs4y",
      "name": "Arsenal",
      "is_mens_team": false,
      "primary_competition": { "id": "competition_5y6lo1sgiuz9", "name": "Women's Super League" }
    },
    {
      "id": "team_oejc59y73fs9",
      "name": "Arsenal U21",
      "is_mens_team": true,
      "primary_competition": { "id": "competition_9z5r9s59u6ch", "name": "Football League Trophy" }
    }
  ],
  "meta": { "page": 1, "per_page": 5, "total": 13, "total_pages": 3 }
}

To tell them apart:

Men's or women's: add is_mens_team=true or is_mens_team=false. The field is null when we don't know.
First team or youth side: look at primary_competition. Arsenal's first team plays in the Premier League; the U21 side doesn't.

To get every team in one season, filter by both competition and season. This returns the 20 Premier League clubs:

curl "https://api.soccer-data.co/v1/teams?competition_id=competition_705uv6jm8myn&season_id=season_hr1ie7yrsdmt" \
  -H "X-Api-Key: YOUR_API_KEY"

Players

Search by name. You need at least three characters, and the search ignores case and accents, so saka works.

curl "https://api.soccer-data.co/v1/players?search=saka&per_page=2" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Other ways to find players:

By team: /players?team_id=team_f0ibhxdw7hs5. Add position=F (or G, D, M) to narrow it down.
A full squad: /teams/team_f0ibhxdw7hs5/players returns the current squad in one response.
Several at once: /players?player_ids=player_ul3vc6om97u5,player_zpfc5xvtigeo with comma-separated ids.

Matches

Matches are found by filtering rather than searching. For example, a team's next match:

curl "https://api.soccer-data.co/v1/matches?team_id=team_f0ibhxdw7hs5&status=scheduled&sort=utc_date&per_page=1" \
  -H "X-Api-Key: YOUR_API_KEY"

You can also filter by competition, season, date range, matchday and more. Fixtures and results covers them all.

Country codes

country_code takes ISO codes such as DE or ES. For the UK, GB covers all four nations; use GB-ENG, GB-SCT, GB-WLS or GB-NIR for just one. If you'd rather use names, the country parameter takes them, as in country=Spain.

Common mistakes

Typing ids by hand or guessing them. An id we don't recognise returns 404 NOT_FOUND. Copy ids from a response.
Mixing up seasons and competitions. A season id only works with its own competition.
Picking the wrong Arsenal. Check is_mens_team and primary_competition before you store a team id.
Searching players with fewer than three characters. Use a longer name.