FOOTBALL RESULTS TODAY API

Today

Complimentary key

Every match settled today so far, by the UTC calendar, in every competition your key reads. On the complimentary key it reads this season's Premier League.

GET/v1/results/today

TRY ITComplimentary

X-API-Key

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

competition

GET https://api.footballapi.org/v1/results/today

The answer appears below, with its status and time.

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

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_degintegerThe 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_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/today, taken 21 Oct 2026, first rows shown

{
  "data": [
    {
      "match_id": "mt_9297jqxps",
      "competition": "liga-mx",
      "country_name": "Mexico",
      "competition_name": "Liga MX",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-21T03:00:00Z",
      "kickoff_date": "2026-10-21",
      "kickoff_local_date": "2026-10-21",
      "kickoff_local_time": "03:00",
      "match_status": "finished",
      "home_club_id": "cl_bjjxdnf2k",
      "home_club_name": "Tigres UANL",
      "away_club_id": "cl_2gmwcrjzv",
      "away_club_name": "Leon",
      "home_goals": 0,
      "away_goals": 2,
      "full_time_result": "away",
      "half_time_home_goals": 0,
      "half_time_away_goals": 1,
      "half_time_result": "away",
      "stoppage_minutes": null,
      "is_kickoff_rescheduled": false,
      "elapsed_minutes": null,
      "home_league_position": 14,
      "away_league_position": 7,
      "away_travel_km": 530,
      "ground_name": "Estadio Universitario",
      "city_name": "Monterey",
      "latitude": 25.722805555556,
      "longitude": -100.31205555556,
      "location_precision": "ground",
      "daylight_minutes": 687,
      "sun_elevation_deg": -39,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": null,
      "referee_name": "Marco Antonio Ortiz Nava",
      "regular_time_home_goals": 0,
      "regular_time_away_goals": 2,
      "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": 1.93,
          "xg_estimate": 1.75,
          "shots": 20,
          "shots_on_target": 6,
          "corners": 16,
          "fouls": 5,
          "yellow_cards": 0,
          "red_cards": 0,
          "possession_pct": 70
        },
        "away": {
          "xg": 2.27,
          "xg_estimate": 1.32,
          "shots": 12,
          "shots_on_target": 5,
          "corners": 4,
          "fouls": 18,
          "yellow_cards": 1,
          "red_cards": 0,
          "possession_pct": 30
        }
      }
    },
    {
      "match_id": "mt_frd5e4m0v",
      "competition": "liga-mx",
      "country_name": "Mexico",
      "competition_name": "Liga MX",
      "season_start_year": 2026,
      "kickoff_utc": "2026-10-21T01:00:00Z",
      "kickoff_date": "2026-10-21",
      "kickoff_local_date": "2026-10-21",
      "kickoff_local_time": "01:00",
      "match_status": "finished",
      "home_club_id": "cl_65j4qj867",
      "home_club_name": "FC Juarez",
      "away_club_id": "cl_0hyxdbdzp",
      "away_club_name": "Atlante FC",
      "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": 16,
      "away_travel_km": 1566,
      "ground_name": "Estadio Olímpico Benito Juárez",
      "city_name": "Ciudad Juarez",
      "latitude": 31.75305,
      "longitude": -106.467814,
      "location_precision": "ground",
      "daylight_minutes": 677,
      "sun_elevation_deg": -7.4,
      "public_holiday": null,
      "kickoff_temperature_c": null,
      "kickoff_rain_mm": null,
      "kickoff_wind_ms": null,
      "attendance": null,
      "referee_name": "Katia García",
      "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.44,
          "xg_estimate": 0.43,
          "shots": 7,
          "shots_on_target": 1,
          "corners": 8,
          "fouls": 18,
          "yellow_cards": 4,
          "red_cards": 0,
          "possession_pct": 61
        },
        "away": {
          "xg": 0.77,
          "xg_estimate": 1.11,
          "shots": 10,
          "shots_on_target": 3,
          "corners": 9,
          "fouls": 22,
          "yellow_cards": 2,
          "red_cards": 0,
          "possession_pct": 39
        }
      }
    }
  ],
  "meta": {
    "count": 4,
    "request_id": "req_de823f78bc3591cc"
  }
}

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.

PREVIOUSResults NEXTYesterday