// Coverage
Season coverage for a competition
Breaks one competition's coverage down season by season: how many matches are finished and what share of them has each kind of data. Use it to see exactly how far back xG, lineups or odds go before you rely on them.
GET
https://api.soccer-data.co/v1/coverage/leagues/{competition_id}
- Every season we know of is listed, including ones with no matches loaded. Check status: not_loaded means there are no matches for that season yet.
- Seasons are not sorted by date.
- odds is an older name for closing_odds, kept so existing code keeps working. opening_odds is the first price seen for each selection; closing_odds is the last one before kick-off.
- New data type keys can appear over time. Skip any you don't recognise.
Path parameters
competition_idstringrequired
The competition's id, like competition_…. Find one with the ID guide.
Response fields
data.idstring
The competition's id.
data.namestring
The competition's name.
data.countrystring
Country name. Can be null.
data.country_codestring
Country code. Can be null.
data.total_seasonsinteger
Every season known for the competition, loaded or not.
data.loaded_seasonsinteger
Seasons with at least one match loaded. Same number as seasons.count in /coverage/leagues.
data.total_finished_eventsinteger
Finished matches across the whole competition.
data.seasons[].idstring
The season's id.
data.seasons[].namestring
The season's display name.
data.seasons[].yearstring
Short label, such as 25/26. Can be null.
data.seasons[].statusstring
complete (every loaded match is played), in_progress (some are still to come) or not_loaded (no matches loaded). Based only on matches loaded so far; more values may be added.
data.seasons[].events.finishedinteger
Matches already played that season.
data.seasons[].events.totalinteger
All matches in that season, played or not.
data.seasons[].data_types.{type}.availableboolean
Whether the season has this kind of data. Keys: fixtures, team_stats, xg, odds, opening_odds, closing_odds, lineups, player_stats and standings.
data.seasons[].data_types.{type}.covered_eventsinteger
Finished matches that have this kind of data. Not every type includes it; standings, for example, only has available.
data.seasons[].data_types.{type}.coverage_pctnumber
covered_events as a percentage of finished matches, to one decimal place. Not every type includes it.
curl "https://api.soccer-data.co/v1/coverage/leagues/competition_705uv6jm8myn" \ -H "X-Api-Key: $SOCCER_DATA_KEY"
const res = await fetch("https://api.soccer-data.co/v1/coverage/leagues/competition_705uv6jm8myn", {
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/coverage/leagues/competition_705uv6jm8myn",
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/coverage/leagues/competition_705uv6jm8myn')
->json('data');
200 · Example response
{
"data": {
"id": "competition_705uv6jm8myn",
"name": "Premier League",
"country": "England",
"country_code": "GB",
"total_seasons": 34,
"loaded_seasons": 13,
"total_finished_events": 4610,
"seasons": [
{
"id": "season_98l95mxugqs9",
"name": "Premier League 25/26",
"year": "25/26",
"status": "complete",
"events": {
"finished": 380,
"total": 380
},
"data_types": {
"fixtures": {
"available": true,
"covered_events": 380
},
"team_stats": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"xg": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"odds": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"opening_odds": {
"available": false,
"covered_events": 0,
"coverage_pct": 0
},
"closing_odds": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"lineups": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"player_stats": {
"available": true,
"covered_events": 380,
"coverage_pct": 100
},
"standings": {
"available": true
}
}
}
]
}
}
### GET /coverage/leagues/{competition_id}
Season coverage for a competition
Breaks one competition's coverage down season by season: how many matches are finished and what share of them has each kind of data. Use it to see exactly how far back xG, lineups or odds go before you rely on them.
- Every season we know of is listed, including ones with no matches loaded. Check status: not_loaded means there are no matches for that season yet.
- Seasons are not sorted by date.
- odds is an older name for closing_odds, kept so existing code keeps working. opening_odds is the first price seen for each selection; closing_odds is the last one before kick-off.
- New data type keys can appear over time. Skip any you don't recognise.
Response fields:
- `data.id` (string): The competition's id.
- `data.name` (string): The competition's name.
- `data.country` (string): Country name. Can be null.
- `data.country_code` (string): Country code. Can be null.
- `data.total_seasons` (integer): Every season known for the competition, loaded or not.
- `data.loaded_seasons` (integer): Seasons with at least one match loaded. Same number as seasons.count in /coverage/leagues.
- `data.total_finished_events` (integer): Finished matches across the whole competition.
- `data.seasons[].id` (string): The season's id.
- `data.seasons[].name` (string): The season's display name.
- `data.seasons[].year` (string): Short label, such as 25/26. Can be null.
- `data.seasons[].status` (string): complete (every loaded match is played), in_progress (some are still to come) or not_loaded (no matches loaded). Based only on matches loaded so far; more values may be added.
- `data.seasons[].events.finished` (integer): Matches already played that season.
- `data.seasons[].events.total` (integer): All matches in that season, played or not.
- `data.seasons[].data_types.{type}.available` (boolean): Whether the season has this kind of data. Keys: fixtures, team_stats, xg, odds, opening_odds, closing_odds, lineups, player_stats and standings.
- `data.seasons[].data_types.{type}.covered_events` (integer): Finished matches that have this kind of data. Not every type includes it; standings, for example, only has available.
- `data.seasons[].data_types.{type}.coverage_pct` (number): covered_events as a percentage of finished matches, to one decimal place. Not every type includes it.
Example: curl "https://api.soccer-data.co/v1/coverage/leagues/competition_705uv6jm8myn" -H "X-Api-Key: $SOCCER_DATA_KEY"