FOOTBALL FIXTURES API

Fixtures

Complimentary keyMCP tool upcoming_fixtures

Matches still to come in the competitions your key reads, soonest first, with kickoff in UTC and the local date. On the complimentary key it reads this season's Premier League.

GET/v1/fixtures

TRY ITComplimentary

X-API-Key

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

competition

date_from

date_to

page

per_page

GET https://api.footballapi.org/v1/fixtures?competition=premier-league&per_page=2

The answer appears below, with its status and time.

curl "https://api.footballapi.org/v1/fixtures?competition=premier-league&per_page=2" \
  -H "X-API-Key: your key"

PARAMETERS

competitionstringA competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads.

date_fromdateFrom this day, YYYY-MM-DD.

date_todateUp to this day, YYYY-MM-DD.

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

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

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_goalsnull or moreHome goals at full time

away_goalsnull or moreAway goals at full time

full_time_resultnull or morehome, away or draw, at full time

half_time_home_goalsnull or moreHome goals at half time

half_time_away_goalsnull or moreAway goals at half time

half_time_resultnull or morehome, away or draw, at half time

stoppage_minutesnull or moreMinutes 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_positionintegerThe home side's place in its league before kickoff

away_league_positionintegerThe 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_cnull or moreThe temperature at kickoff, in degrees C; null when not recorded

kickoff_rain_mmnull or moreRain in the hour of kickoff, in millimetres; null when not recorded

kickoff_wind_msnull or moreWind at kickoff, in metres a second; null when not recorded

attendancenull or moreThe crowd; null when not recorded

referee_namenull or moreThe referee

regular_time_home_goalsnull or moreHome goals after 90 minutes and added time

regular_time_away_goalsnull or moreAway goals after 90 minutes and added time

regular_time_resultnull or morehome, 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_figuresnull or moreEach side's figures for the match

EXAMPLE ANSWER

200GET /v1/fixtures?competition=premier-league&per_page=2, taken 21 Oct 2026

{
  "data": [
    {
      "match_id": "mt_47y6n1wr1",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-23T19:00:00Z",
      "kickoff_date": "2026-10-23",
      "kickoff_local_date": "2026-10-23",
      "kickoff_local_time": "19:00",
      "match_status": "scheduled",
      "home_club_id": "cl_6hrwkbdmn",
      "home_club_name": "Ipswich",
      "away_club_id": "cl_5bvjqjxyw",
      "away_club_name": "Nottingham Forest",
      "home_goals": null,
      "away_goals": null,
      "full_time_result": null,
      "half_time_home_goals": null,
      "half_time_away_goals": null,
      "half_time_result": null,
      "stoppage_minutes": null,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": 10,
      "away_league_position": 19,
      "away_travel_km": 183,
      "ground_name": "Portman Road Stadium",
      "city_name": "Ipswich",
      "latitude": 52.059444444444,
      "longitude": 1.1555555555556,
      "location_precision": "city",
      "daylight_minutes": 613,
      "sun_elevation_deg": -21.2,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": null,
      "referee_name": null,
      "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,
      "club_figures": null
    },
    {
      "match_id": "mt_2yj81sb7s",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-24T11:30:00Z",
      "kickoff_date": "2026-10-24",
      "kickoff_local_date": "2026-10-24",
      "kickoff_local_time": "11:30",
      "match_status": "scheduled",
      "home_club_id": "cl_7me91q2ds",
      "home_club_name": "Aston Villa",
      "away_club_id": "cl_a7vhnxhhh",
      "away_club_name": "Manchester City",
      "home_goals": null,
      "away_goals": null,
      "full_time_result": null,
      "half_time_home_goals": null,
      "half_time_away_goals": null,
      "half_time_result": null,
      "stoppage_minutes": null,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": 12,
      "away_league_position": 1,
      "away_travel_km": 110,
      "ground_name": "Villa Park",
      "city_name": "Birmingham",
      "latitude": 52.509166666667,
      "longitude": -1.8847222222222,
      "location_precision": "ground",
      "daylight_minutes": 609,
      "sun_elevation_deg": 25.8,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": null,
      "referee_name": null,
      "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,
      "club_figures": null
    }
  ],
  "meta": {
    "count": 2,
    "page": 1,
    "per_page": 2,
    "total": 30,
    "total_pages": 15,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": null,
    "request_id": "req_ccace595cb6e7d84"
  }
}

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.

PREVIOUSLatest NEXTToday