Documentation / Matches
FOOTBALL MATCHES API
MatchesComplimentary keyMCP tool
find_matchesEvery match in the collection, played or still to come, found by competition, club, season, dates, status, result, surface or home and away, paged. On the complimentary key it reads this season's Premier League.
GET
/v1/matchesTRY ITComplimentary
Kept in this browser for every docs page. No key yet? Get a free key
GET https://api.footballapi.org/v1/matches?competition=premier-league&season=2026&per_page=2The answer appears below, with its status and time.
curl "https://api.footballapi.org/v1/matches?competition=premier-league&season=2026&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.clubstringOnly this club's matches: a club id such as cl_a7vhnxhhh.seasonintegerThe first year of the season: 2026 for 2026/27.From 2015, or the competition's first seasondate_fromdateFrom this day, YYYY-MM-DD.date_todateUp to this day, YYYY-MM-DD.statusstringWhere the match stands.finished or scheduled or postponed or cancelled or abandonedresultstringHow it ended, from the home side: home, draw or away.home or draw or awaysurfacestringThe pitch.grass or artificial_turfvenuestringHome matches only, or away matches only.home or awaypageintegerWhich page, from 1.From 1 to 100,000per_pageintegerRows on a page. Default 100.From 1 to 1,000cursorstringmeta.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 goodcompetitionstringThe competition's name in the collection, such as premier-leaguecountry_namestringThe country, or World or Europe for a tournamentcompetition_namestringThe competition as people write itseason_start_yearintegerThe first year of the season: 2026 for 2026/27kickoff_utcstringKickoff in UTC, ISO 8601kickoff_datestringThe day of kickoff in UTC, YYYY-MM-DDkickoff_local_datestringThe day of kickoff where the match is playedkickoff_local_timestringThe time of kickoff where the match is playedmatch_statusstringWhere the match stands, such as finished or not startedhome_club_idstringOur id for the home clubhome_club_namestringThe home clubaway_club_idstringOur id for the away clubaway_club_namestringThe away clubhome_goalsnull or moreHome goals at full timeaway_goalsnull or moreAway goals at full timefull_time_resultnull or morehome, away or draw, at full timehalf_time_home_goalsnull or moreHome goals at half timehalf_time_away_goalsnull or moreAway goals at half timehalf_time_resultnull or morehome, away or draw, at half timestoppage_minutesnull or moreMinutes of added time; null when not recordedis_kickoff_rescheduledbooleanWhether kickoff moved from its first date or timeelapsed_minutesnull or moreMinutes played so far while the match is on; null otherwisehome_league_positionintegerThe home side's place in its league before kickoffaway_league_positionintegerThe away side's place in its league before kickoffaway_travel_kmintegerHow far the away side came, ground to ground, in kilometresground_namestringThe groundcity_namestringThe city of the groundlatitudenumberWhere the ground is, north to southlongitudenumberWhere the ground is, east to westlocation_precisionstringHow exact latitude and longitude are: ground, or citydaylight_minutesintegerMinutes of daylight that day at the groundsun_elevation_degnumberThe sun's height at kickoff, in degrees; below 0 after darkpublic_holidaynull or moreThe public holiday that day where the match is played; null when nonekickoff_temperature_cnull or moreThe temperature at kickoff, in degrees C; null when not recordedkickoff_rain_mmnull or moreRain in the hour of kickoff, in millimetres; null when not recordedkickoff_wind_msnull or moreWind at kickoff, in metres a second; null when not recordedattendancenull or moreThe crowd; null when not recordedreferee_namenull or moreThe refereeregular_time_home_goalsnull or moreHome goals after 90 minutes and added timeregular_time_away_goalsnull or moreAway goals after 90 minutes and added timeregular_time_resultnull or morehome, away or draw, after 90 minutes and added timeextra_time_home_goalsnull or moreHome goals after extra time; null when there was noneextra_time_away_goalsnull or moreAway goals after extra time; null when there was noneshootout_home_goalsnull or moreHome penalties scored in a shootout; null when there was noneshootout_away_goalsnull or moreAway penalties scored in a shootout; null when there was noneclub_figuresnull or moreEach side's figures for the matchEXAMPLE ANSWER
200GET /v1/matches?competition=premier-league&season=2026&per_page=2, taken 21 Oct 2026
{ "data": [ { "match_id": "mt_d1gds0xhp", "competition": "premier-league", "country_name": "England", "competition_name": "Premier League", "season_start_year": 2026, "kickoff_utc": "2027-05-30T15:00:00Z", "kickoff_date": "2027-05-30", "kickoff_local_date": "2027-05-30", "kickoff_local_time": "15:00", "match_status": "scheduled", "home_club_id": "cl_e0nqz3rc3", "home_club_name": "Sunderland", "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": 20, "away_league_position": 1, "away_travel_km": 168, "ground_name": "Stadium of Light", "city_name": "Sunderland", "latitude": 54.914429068932, "longitude": -1.3881729713502, "location_precision": "ground", "daylight_minutes": 1011, "sun_elevation_deg": 43.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_06ythj4n7", "competition": "premier-league", "country_name": "England", "competition_name": "Premier League", "season_start_year": 2026, "kickoff_utc": "2027-05-30T15:00:00Z", "kickoff_date": "2027-05-30", "kickoff_local_date": "2027-05-30", "kickoff_local_time": "15:00", "match_status": "scheduled", "home_club_id": "cl_3pekhsfp3", "home_club_name": "Manchester United", "away_club_id": "cl_6ccybzgsq", "away_club_name": "Fulham", "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": 13, "away_league_position": 18, "away_travel_km": 262, "ground_name": "Old Trafford", "city_name": "Manchester", "latitude": 53.463055555556, "longitude": -2.2913888888889, "location_precision": "ground", "daylight_minutes": 994, "sun_elevation_deg": 44.3, "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": 380, "total_pages": 190, "next_page": 2, "prev_page": null, "next_cursor": "VaHW-WftqcvrOsFaVoRrFeYDLvSP8cNb0K-avynYtAanqfKmBBIwV5FA6VwtB57L6AKnMg", "request_id": "req_3a7975b734a2ada3" } }
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.