Search competitions

Returns leagues, cups and tournaments, 20 per page by default. Use it to look up a competition_id by name or country, then pass that id to the matches, teams and standings endpoints.

curl "https://api.soccer-data.co/v1/competitions?search=Premier+League" \
  -H "X-Api-Key: $SOCCER_DATA_KEY"

const res = await fetch("https://api.soccer-data.co/v1/competitions?search=Premier+League", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/competitions",
    params={"search": "Premier League"},
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/competitions', ['search' => 'Premier League'])
    ->json('data');

{
    "data": [
        {
            "id": "competition_705uv6jm8myn",
            "name": "Premier League",
            "country": "England",
            "country_code": "GB",
            "subdivision_code": "GB-ENG",
            "confederation": null,
            "type": "league",
            "has_team_stats": true,
            "has_player_stats": true,
            "odds_available": true,
            "live_odds_available": false,
            "xg_available": true
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

### GET /competitions

Search competitions

Returns leagues, cups and tournaments, 20 per page by default. Use it to look up a competition_id by name or country, then pass that id to the matches, teams and standings endpoints.
- country_code=GB brings back English, Scottish, Welsh and Northern Irish competitions together. Use GB-ENG, GB-SCT, GB-WLS or GB-NIR for just one of them.
- Asking for a page past the last one returns 400 PAGE_OUT_OF_RANGE.

Query parameters:
- `search` (string): Part of the competition name, case-insensitive. With sort=relevance the closest match comes first.
- `country` (string): Country name, case-insensitive, for example England or Spain.
- `country_code` (string): A code as it appears in country_code or subdivision_code, such as GB, GB-ENG, DE or ES. GB covers all four UK nations.
- `type` (string, one of league, cup, tournament): Only competitions of this format.
- `sort` (string, default "relevance", one of relevance, name): relevance puts the best matches for search first; name orders results A to Z. Without search, both give A to Z.
- `page` (integer, default 1): Which page to return, starting at 1. meta.total_pages tells you how many there are.
- `per_page` (integer, default 20): How many results per page, from 1 to 100.

Response fields:
- `data[].id` (string): The competition's id. Pass it as competition_id to other endpoints.
- `data[].name` (string): The competition's name.
- `data[].country` (string): Country name. Null for international and continental competitions; see confederation for those.
- `data[].country_code` (string): Two-letter ISO 3166 country code, such as GB. Null for international competitions. UK nations are told apart in subdivision_code.
- `data[].subdivision_code` (string): ISO 3166-2 code for competitions in England, Scotland, Wales or Northern Ireland: GB-ENG, GB-SCT, GB-WLS or GB-NIR. Null everywhere else.
- `data[].confederation` (string): The governing body of an international competition: UEFA, CONMEBOL, FIFA, CAF, AFC, CONCACAF or OFC. Null for domestic competitions.
- `data[].type` (string): The format: league, cup or tournament.
- `data[].has_team_stats` (boolean): True when team statistics exist for this competition.
- `data[].has_player_stats` (boolean): True when player statistics exist for this competition.
- `data[].odds_available` (boolean): True when bookmaker odds exist for its matches, either pre-match prices or stored closing prices.
- `data[].live_odds_available` (boolean): True when at least one of its matches has in-play odds right now.
- `data[].xg_available` (boolean): True when expected goals (xG) data exists, with at least one non-zero value.
- `meta.page` (integer): The page you're on.
- `meta.per_page` (integer): Results per page.
- `meta.total` (integer): Matching competitions across all pages.
- `meta.total_pages` (integer): How many pages there are.

Example: curl "https://api.soccer-data.co/v1/competitions?search=Premier+League" -H "X-Api-Key: $SOCCER_DATA_KEY"