FOOTBALL MATCH DATA API

Match

Complimentary keyMCP tool get_match

Everything about a match: the score at every stage, both clubs' positions before kickoff, the ground, the referee and the conditions on the day. On the complimentary key it reads this season's Premier League.

GET/v1/matches/{match_id}

TRY ITComplimentary

X-API-Key

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

match_idrequired

GET https://api.footballapi.org/v1/matches/mt_95kf4jw9a

The answer appears below, with its status and time.

curl "https://api.footballapi.org/v1/matches/mt_95kf4jw9a" \
  -H "X-API-Key: your key"

PARAMETERS

match_idrequiredstringA match id from any result, fixture or match list, such as mt_e2hk79mn5. In the path.

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

home_formationstringThe home side's formation, such as 4-2-3-1

away_formationstringThe away side's formation

ground_idstringOur id for the ground, gd_ and 9 characters

capacityintegerHow many the ground holds

surfacestringThe pitch, such as grass

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

statslistEach side's figures for the match

stats[].club_namestringThe club

stats[].statsobjectEach side's figures for the match

stats[].stats.cornersintegerCorners

stats[].stats.expected_goalsnumberExpected goals

stats[].stats.foulsintegerFouls committed

stats[].stats.free_kicksintegerFree kicks

stats[].stats.offsidesintegerTimes caught offside

stats[].stats.passes_accurateintegerPasses that reached a team-mate

stats[].stats.passes_totalintegerPasses

stats[].stats.possession_pctintegerShare of the ball, as a percentage

stats[].stats.red_cardsintegerRed cards

stats[].stats.savesintegerSaves by the goalkeeper

stats[].stats.shots_blockedintegerShots blocked

stats[].stats.shots_inside_boxintegerShots from inside the penalty area

stats[].stats.shots_off_targetintegerShots off target

stats[].stats.shots_on_targetintegerShots on target

stats[].stats.shots_outside_boxintegerShots from outside the penalty area

stats[].stats.shots_totalintegerShots

stats[].stats.yellow_cardsintegerYellow cards

EXAMPLE ANSWER

200GET /v1/matches/mt_95kf4jw9a, 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,
    "home_formation": "3-4-2-1",
    "away_formation": "4-2-3-1",
    "ground_id": "gd_4wv42jcr4",
    "capacity": 62850,
    "surface": "grass",
    "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
      }
    },
    "stats": [
      {
        "club_name": "Tottenham",
        "stats": {
          "corners": 4,
          "expected_goals": 0.9,
          "fouls": 15,
          "free_kicks": 14,
          "offsides": 6,
          "passes_accurate": 499,
          "passes_total": 559,
          "possession_pct": 66,
          "red_cards": 0,
          "saves": 0,
          "shots_blocked": 4,
          "shots_inside_box": 10,
          "shots_off_target": 7,
          "shots_on_target": 5,
          "shots_outside_box": 6,
          "shots_total": 16,
          "yellow_cards": 1
        }
      },
      {
        "club_name": "Coventry",
        "stats": {
          "corners": 4,
          "expected_goals": 0.83,
          "fouls": 14,
          "free_kicks": 15,
          "offsides": 1,
          "passes_accurate": 221,
          "passes_total": 285,
          "possession_pct": 34,
          "red_cards": 0,
          "saves": 2,
          "shots_blocked": 4,
          "shots_inside_box": 11,
          "shots_off_target": 7,
          "shots_on_target": 1,
          "shots_outside_box": 1,
          "shots_total": 12,
          "yellow_cards": 3
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_06c6b9a0356d2a31"
  }
}

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.

PREVIOUSMatches NEXTEvents