FOOTBALL RESULTS API

Results

Complimentary keyMCP tool find_results

Settled matches newest first, by day, by date range, by competition or by club, paged. Every season goes back to 2015/16, or to the league's start. On the complimentary key it reads this season's Premier League.

GET/v1/results

TRY ITComplimentary

X-API-Key

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

competition

club

date

date_from

date_to

page

per_page

cursor

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

The answer appears below, with its status and time.

curl "https://api.footballapi.org/v1/results?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.

clubstringOnly this club's matches: a club id such as cl_a7vhnxhhh.

datedateOne day, YYYY-MM-DD.

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

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_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

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/results?competition=premier-league&per_page=2, taken 21 Oct 2026

{
  "data": [
    {
      "match_id": "mt_95kf4jw9a",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-19T19:00:00Z",
      "kickoff_date": "2026-10-19",
      "kickoff_local_date": "2026-10-19",
      "kickoff_local_time": "19:00",
      "match_status": "finished",
      "home_club_id": "cl_4x2bczxvv",
      "home_club_name": "Tottenham",
      "away_club_id": "cl_frt0n2e46",
      "away_club_name": "Coventry",
      "home_goals": 3,
      "away_goals": 1,
      "full_time_result": "home",
      "half_time_home_goals": 1,
      "half_time_away_goals": 0,
      "half_time_result": "home",
      "stoppage_minutes": null,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": 20,
      "away_league_position": 16,
      "away_travel_km": 135,
      "ground_name": "Tottenham Hotspur Stadium",
      "city_name": "London",
      "latitude": 51.604444444444,
      "longitude": -0.066388888888889,
      "location_precision": "ground",
      "daylight_minutes": 630,
      "sun_elevation_deg": -19.3,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": 60913,
      "referee_name": "Andrew Madley",
      "regular_time_home_goals": 3,
      "regular_time_away_goals": 1,
      "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": 0.9,
          "xg_estimate": 1.66,
          "shots": 16,
          "shots_on_target": 5,
          "corners": 4,
          "fouls": 15,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 66
        },
        "away": {
          "xg": 0.83,
          "xg_estimate": 1.34,
          "shots": 12,
          "shots_on_target": 1,
          "corners": 4,
          "fouls": 14,
          "yellow_cards": 3,
          "red_cards": 0,
          "possession_pct": 34
        }
      }
    },
    {
      "match_id": "mt_3pfb14gzr",
      "competition": "premier-league",
      "country_name": "England",
      "competition_name": "Premier League",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-18T15:30:00Z",
      "kickoff_date": "2026-10-18",
      "kickoff_local_date": "2026-10-18",
      "kickoff_local_time": "15:30",
      "match_status": "finished",
      "home_club_id": "cl_5bvjqjxyw",
      "home_club_name": "Nottingham Forest",
      "away_club_id": "cl_9cbmhewrg",
      "away_club_name": "Arsenal",
      "home_goals": 0,
      "away_goals": 1,
      "full_time_result": "away",
      "half_time_home_goals": 0,
      "half_time_away_goals": 0,
      "half_time_result": "draw",
      "stoppage_minutes": null,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": 18,
      "away_league_position": 3,
      "away_travel_km": 169,
      "ground_name": "City Ground",
      "city_name": "Nottingham",
      "latitude": 52.94,
      "longitude": -1.132778,
      "location_precision": "ground",
      "daylight_minutes": 630,
      "sun_elevation_deg": 12.1,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": 30893,
      "referee_name": "Michael Oliver",
      "regular_time_home_goals": 0,
      "regular_time_away_goals": 1,
      "regular_time_result": "away",
      "extra_time_home_goals": null,
      "extra_time_away_goals": null,
      "shootout_home_goals": null,
      "shootout_away_goals": null,
      "club_figures": {
        "home": {
          "xg": 0.79,
          "xg_estimate": 1.1,
          "shots": 14,
          "shots_on_target": 2,
          "corners": 8,
          "fouls": 14,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 26
        },
        "away": {
          "xg": 1.09,
          "xg_estimate": 0.89,
          "shots": 9,
          "shots_on_target": 1,
          "corners": 6,
          "fouls": 8,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 74
        }
      }
    }
  ],
  "meta": {
    "count": 2,
    "page": 1,
    "per_page": 2,
    "total": 14446,
    "total_pages": 7223,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": "uAIfpUPNnzUavfl_M-pg_XaOxXFDwItzDe9-0s_bm5TCAvcK_roiyZ88DdhFqRM1ovRYfw",
    "request_id": "req_dc5191a88e65250a"
  }
}

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.

PREVIOUSMatch stats NEXTToday