The free key reads yesterday again: our one-month trial of today on the free key has finished. Read the changelog
Free API key Register free

Coverage

F
GET /v1/coverage

What every competition-season holds, in one list

What every competition and season holds, one row each, newest first: matches, settled matches, and the share of settled matches carrying kickoff prices, half-time prices, team statistics, lineups, goal events, a half-time score, a referee, a ground and an exchange market. Make it your first call: it says what you will get for a competition before you build on it. Counted at every nightly rebuild.

Plan

This endpoint needs Free key. It works on the free key, which reads yesterday, as one whole day.

Parameters

league_id string query
Restrict to one competition. Ids come from /v1/leagues: 39 is the English Premier League, 62 is Ligue 2. e.g. lg_24T9Z0G
country string query
Restrict to one country, by name as returned from /v1/countries. e.g. England
season integer query
Season by its starting year. A 2024/25 season is 2024. e.g. 2024
min_matches integer query
Leave out teams rated on fewer matches than this. Defaults to 20. e.g. 50
page integer query
Page number, 1-based. The response carries total, total_pages, next_page and prev_page, so a UI pager has everything it needs from one call. If you send both page and cursor, page wins. e.g. 2
limit integer query
Rows per page, 1–1000. Defaults to 100. e.g. 100

Returns

data.match_id string
Our id for the match. Stable: what you store today still resolves later.
data.league_id string
Our id for the competition.
data.country_name string
The country the competition belongs to.
data.league_name string
The competition's name.
data.season_start_year integer
The year the season starts in: 2026 for 2026/27.
data.kickoff_utc integer
Kickoff, as a UTC timestamp.
data.kickoff_date string
The kickoff date in UTC, YYYY-MM-DD.
data.kickoff_local_time string
The kickoff time where the match is played, HH:MM.
data.match_status string
Where the match stands: scheduled, in play by half, half time, finished, postponed, cancelled, abandoned, awarded or walkover.
data.home_team_id string
Our id for the home side.
data.home_team_name string
The home side's name.
data.away_team_id string
Our id for the away side.
data.away_team_name string
The away side's name.
data.home_goals integer
The home side's goals: the final score, after extra time where played.
data.away_goals integer
The away side's goals: the final score, after extra time where played.
data.full_time_result empty in this example
home, draw or away, on the final score.
data.half_time_home_goals integer
The home side's goals at half time.
data.half_time_away_goals integer
The away side's goals at half time.
data.half_time_result string
home, draw or away at half time.
data.half_time_source string
Half time source.
data.stoppage_minutes empty in this example
Stoppage time added, in minutes.
data.is_kickoff_rescheduled boolean
Whether the kickoff was moved from its first date or time.
data.home_league_position integer
The home side's place in the table before the match.
data.away_league_position integer
The away side's place in the table before the match.
data.away_travel_km integer
How far the away side travelled, in kilometres.
data.venue_name string
The ground the match was played at.
data.city_name string
The town or city of the ground.
data.latitude number
The ground's latitude.
data.longitude number
The ground's longitude.
data.location_precision string
How exact the ground's position is: the ground itself, or only its town.
data.daylight_minutes integer
Minutes of daylight left at kickoff; negative after dark.
data.sun_elevation_deg number
The sun's height above the horizon at kickoff, in degrees.
data.public_holiday empty in this example
Public holiday.
data.referee_name string
The referee.
data.regular_time_home_goals empty in this example
The home side's goals after 90 minutes.
data.regular_time_away_goals empty in this example
The away side's goals after 90 minutes.
data.regular_time_result empty in this example
home, draw or away after 90 minutes: the result prices settle on.
data.extra_time_home_goals empty in this example
The home side's goals in extra time alone.
data.extra_time_away_goals empty in this example
The away side's goals in extra time alone.
data.shootout_home_goals empty in this example
The home side's penalties scored in the shootout.
data.shootout_away_goals empty in this example
The away side's penalties scored in the shootout.
data.betfair object
Betfair.
data.betfair.home_kickoff_price number
The price for a home win at kickoff, as decimal odds.
data.betfair.draw_kickoff_price number
The price for the draw at kickoff, as decimal odds.
data.betfair.away_kickoff_price number
The price for an away win at kickoff, as decimal odds.
data.betfair.home_half_time_price empty in this example
Home half time price.
data.betfair.matched_kickoff_volume empty in this example
Matched kickoff volume.
data.betfair.market_id empty in this example
Market: our id, stable.
meta.data_as_of string
When the data behind this answer was last brought up to date.
meta.request_id string
This request's id, to quote to support.

Request

curl "https://api.footballsoccerapi.com/v1/coverage?league_id=lg_24T9Z0G&country=England&season=2024" \
  -H "X-API-Key: $FSAPI_KEY"

Example response

A real row from the archive, fetched when this page rendered. Run it against your own key below.

200 OK application/json 
{
    "data": {
        "match_id": "mt_28QVFGW",
        "league_id": "lg_3JZKJSZ",
        "country_name": "Colombia",
        "league_name": "Primera A",
        "season_start_year": 2026,
        "kickoff_utc": 1793228400,
        "kickoff_date": "2026-10-28",
        "kickoff_local_time": "23:00",
        "match_status": "finished",
        "home_team_id": "tm_1HXBKY8",
        "home_team_name": "Once Caldas",
        "away_team_id": "tm_2DNYS20",
        "away_team_name": "Alianza Valledupar",
        "home_goals": 1,
        "away_goals": 0,
        "full_time_result": null,
        "half_time_home_goals": 0,
        "half_time_away_goals": 0,
        "half_time_result": "draw",
        "half_time_source": "feed",
        "stoppage_minutes": null,
        "is_kickoff_rescheduled": false,
        "home_league_position": 7,
        "away_league_position": 16,
        "away_travel_km": 650,
        "venue_name": "Estadio Palogrande",
        "city_name": "Manizales",
        "latitude": 5.056233,
        "longitude": -75.489807,
        "location_precision": "ground",
        "daylight_minutes": 717,
        "sun_elevation_deg": -4.6,
        "public_holiday": null,
        "referee_name": "Carlos Alberto Diaz Vargas",
        "regular_time_home_goals": null,
        "regular_time_away_goals": null,
        "regular_time_result": null,
        "extra_time_home_goals": null,
        "extra_time_away_goals": null,
        "shootout_home_goals": null,
        "shootout_away_goals": null,
        "betfair": {
            "home_kickoff_price": 1.58,
            "draw_kickoff_price": 3.7,
            "away_kickoff_price": 6.25,
            "home_half_time_price": null,
            "matched_kickoff_volume": null,
            "market_id": null
        }
    },
    "meta": {
        "data_as_of": "2026-10-29T04:32:57Z",
        "request_id": "01J9QW3C7M4KX2VB"
    }
}

Run it live

Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.

Get a key
GET
← All endpoints Get a free key →