FOOTBALL SEASON MATCHES API

Season matches

Complimentary key

Every match of a competition in one season, in kickoff order, played and still to come, paged. On the complimentary key it reads this season's Premier League.

GET/v1/competitions/{competition}/seasons/{season}/matches

TRY ITComplimentary

X-API-Key

Kept in this browser for every docs page. No key yet? Get a free key

competitionrequired

seasonrequired

page

per_page

cursor

GET https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/matches?per_page=2

The answer appears below, with its status and time.

curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/matches?per_page=2" \
  -H "X-API-Key: your key"

PARAMETERS

competitionrequiredstringA competition from /v1/competitions, such as premier-league. In the path.

seasonrequiredintegerThe first year of the season: 2026 for 2026/27. In the path.From 2015, or the competition's first season

pageintegerWhich page, from 1.From 1 to 100,000

per_pageintegerRows on a page. Default 100.From 1 to 1,000

cursorstringmeta.next_cursor from the page before, passed back unchanged. Faster than page for long walks.

RETURNS

match_idstringOur id for the match, mt_ and 9 characters, the same in every answer and for good

competitionstringThe competition's name in the collection, such as premier-league

country_namestringThe country, or World or Europe for a tournament

competition_namestringThe competition as people write it

season_start_yearintegerThe first year of the season: 2026 for 2026/27

kickoff_utcstringKickoff in UTC, ISO 8601

kickoff_datestringThe day of kickoff in UTC, YYYY-MM-DD

kickoff_local_datestringThe day of kickoff where the match is played

kickoff_local_timestringThe time of kickoff where the match is played

match_statusstringWhere the match stands, such as finished or not started

home_club_idstringOur id for the home club

home_club_namestringThe home club

away_club_idstringOur id for the away club

away_club_namestringThe away club

home_goalsintegerHome goals at full time

away_goalsintegerAway goals at full time

full_time_resultstringhome, away or draw, at full time

half_time_home_goalsintegerHome goals at half time

half_time_away_goalsintegerAway goals at half time

half_time_resultstringhome, away or draw, at half time

stoppage_minutesintegerMinutes of added time; null when not recorded

is_kickoff_rescheduledbooleanWhether kickoff moved from its first date or time

elapsed_minutesnull or moreMinutes played so far while the match is on; null otherwise

home_league_positionnull or moreThe home side's place in its league before kickoff

away_league_positionnull or moreThe away side's place in its league before kickoff

away_travel_kmintegerHow far the away side came, ground to ground, in kilometres

ground_namestringThe ground

city_namestringThe city of the ground

latitudenumberWhere the ground is, north to south

longitudenumberWhere the ground is, east to west

location_precisionstringHow exact latitude and longitude are: ground, or city

daylight_minutesintegerMinutes of daylight that day at the ground

sun_elevation_degnumberThe sun's height at kickoff, in degrees; below 0 after dark

public_holidaynull or moreThe public holiday that day where the match is played; null when none

kickoff_temperature_cnumberThe temperature at kickoff, in degrees C; null when not recorded

kickoff_rain_mmnumberRain in the hour of kickoff, in millimetres; null when not recorded

kickoff_wind_msnumberWind at kickoff, in metres a second; null when not recorded

attendanceintegerThe crowd; null when not recorded

referee_namestringThe referee

regular_time_home_goalsintegerHome goals after 90 minutes and added time

regular_time_away_goalsintegerAway goals after 90 minutes and added time

regular_time_resultstringhome, away or draw, after 90 minutes and added time

extra_time_home_goalsnull or moreHome goals after extra time; null when there was none

extra_time_away_goalsnull or moreAway goals after extra time; null when there was none

shootout_home_goalsnull or moreHome penalties scored in a shootout; null when there was none

shootout_away_goalsnull or moreAway penalties scored in a shootout; null when there was none

club_figuresobjectEach side's figures for the match

club_figures.homeobjectThe home side

club_figures.home.xgnumberExpected goals

club_figures.home.xg_estimatenumberExpected goals worked out from the shots and the other figures

club_figures.home.shotsintegerShots

club_figures.home.shots_on_targetintegerShots on target

club_figures.home.cornersintegerCorners

club_figures.home.foulsintegerFouls committed

club_figures.home.yellow_cardsintegerYellow cards

club_figures.home.red_cardsintegerRed cards

club_figures.home.possession_pctintegerShare of the ball, as a percentage

club_figures.awayobjectThe away side

club_figures.away.xgnumberExpected goals

club_figures.away.xg_estimatenumberExpected goals worked out from the shots and the other figures

club_figures.away.shotsintegerShots

club_figures.away.shots_on_targetintegerShots on target

club_figures.away.cornersintegerCorners

club_figures.away.foulsintegerFouls committed

club_figures.away.yellow_cardsintegerYellow cards

club_figures.away.red_cardsintegerRed cards

club_figures.away.possession_pctintegerShare of the ball, as a percentage

EXAMPLE ANSWER

200GET /v1/competitions/premier-league/seasons/2026/matches?per_page=2, taken 21 Oct 2026

{
  "data": [
    {
      "match_id": "mt_146444zr9",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-08-21T19:00:00Z",
      "kickoff_date": "2026-08-21",
      "kickoff_local_date": "2026-08-21",
      "kickoff_local_time": "19:00",
      "match_status": "finished",
      "home_club_id": "cl_9cbmhewrg",
      "home_club_name": "Arsenal",
      "away_club_id": "cl_frt0n2e46",
      "away_club_name": "Coventry",
      "home_goals": 3,
      "away_goals": 0,
      "full_time_result": "home",
      "half_time_home_goals": 2,
      "half_time_away_goals": 0,
      "half_time_result": "home",
      "stoppage_minutes": 5,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": null,
      "away_league_position": null,
      "away_travel_km": 137,
      "ground_name": "Emirates Stadium",
      "city_name": "London",
      "latitude": 51.555,
      "longitude": -0.10833333333333,
      "location_precision": "ground",
      "daylight_minutes": 859,
      "sun_elevation_deg": 1.1,
      "public_holiday": null,
      "kickoff_temperature_c": 16.1,
      "kickoff_rain_mm": 0.01,
      "kickoff_wind_ms": 4.4,
      "attendance": 60098,
      "referee_name": "Thomas Bramall",
      "regular_time_home_goals": 3,
      "regular_time_away_goals": 0,
      "regular_time_result": "home",
      "extra_time_home_goals": null,
      "extra_time_away_goals": null,
      "shootout_home_goals": null,
      "shootout_away_goals": null,
      "club_figures": {
        "home": {
          "xg": 1.88,
          "xg_estimate": 1.75,
          "shots": 20,
          "shots_on_target": 6,
          "corners": 8,
          "fouls": 10,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 64
        },
        "away": {
          "xg": 0.2,
          "xg_estimate": 0.21,
          "shots": 4,
          "shots_on_target": 1,
          "corners": 2,
          "fouls": 13,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 36
        }
      }
    },
    {
      "match_id": "mt_9bf725d14",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-08-22T11:30:00Z",
      "kickoff_date": "2026-08-22",
      "kickoff_local_date": "2026-08-22",
      "kickoff_local_time": "11:30",
      "match_status": "finished",
      "home_club_id": "cl_bp6fqwzpj",
      "home_club_name": "Hull City",
      "away_club_id": "cl_3pekhsfp3",
      "away_club_name": "Manchester United",
      "home_goals": 2,
      "away_goals": 0,
      "full_time_result": "home",
      "half_time_home_goals": 2,
      "half_time_away_goals": 0,
      "half_time_result": "home",
      "stoppage_minutes": 7,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": null,
      "away_league_position": null,
      "away_travel_km": 131,
      "ground_name": "MKM Stadium",
      "city_name": "Hull",
      "latitude": 53.746111111111,
      "longitude": -0.36777777777778,
      "location_precision": "ground",
      "daylight_minutes": 868,
      "sun_elevation_deg": 47.7,
      "public_holiday": null,
      "kickoff_temperature_c": 19.2,
      "kickoff_rain_mm": 0.01,
      "kickoff_wind_ms": 3,
      "attendance": 24470,
      "referee_name": "Darren England",
      "regular_time_home_goals": 2,
      "regular_time_away_goals": 0,
      "regular_time_result": "home",
      "extra_time_home_goals": null,
      "extra_time_away_goals": null,
      "shootout_home_goals": null,
      "shootout_away_goals": null,
      "club_figures": {
        "home": {
          "xg": 1.01,
          "xg_estimate": 0.99,
          "shots": 8,
          "shots_on_target": 4,
          "corners": 1,
          "fouls": 10,
          "yellow_cards": 2,
          "red_cards": 0,
          "possession_pct": 28
        },
        "away": {
          "xg": 1.83,
          "xg_estimate": 2.22,
          "shots": 21,
          "shots_on_target": 5,
          "corners": 6,
          "fouls": 9,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 72
        }
      }
    }
  ],
  "meta": {
    "count": 2,
    "page": 1,
    "per_page": 2,
    "total": 380,
    "total_pages": 190,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": "A-T6AyCUnqZp_hdnmJlgdgkYxVxvVmWFMb7DznzlqYcymSomuLvR-gngjpejhhBoj_zofw",
    "request_id": "req_36846376b2cd28a9"
  }
}

ERRORS

401unauthorizedNo key, or a key we do not know.

400bad_requestA parameter is missing or not in the right form; the message names it.

403upgrade_requiredAnything outside this season's Premier League, on the complimentary key.

404not_foundAn id or competition we do not have.

422unknown_parameterA parameter this endpoint does not take.

429quota_exceededThe day's 50 calls are used, on the complimentary key; they reset at 00:00 UTC.

PREVIOUSSeason clubs NEXTSeason stats