Match detail

GET /v1/matches/{id}

One match, every field it carries

One match with everything the row carries: score, half-time score, both clubs' league position at kickoff, how far the away side travelled, the ground and its coordinates, and the exchange market. Fetching more than one? Do not call this in a loop: /v1/matches?ids= takes up to fifty match ids in a single request, separated by a dash, which is one round trip instead of fifty. See batch requests. Every match, here and on every list, carries team_figures: xG, shots, shots on target, corners, fouls, yellow and red cards and possession for each side, or null where the match had no statistics. xg is measured expected goals, held from 2022; xg_estimate is our own, worked out from the shots each side took (inside and outside the box, and on target) on every match with shot figures, so it reaches back years further. The full statistics block and the line-ups come back only here.

Plan

This endpoint needs Free key. It works on the free key, which reads yesterday, as one whole day.

Parameters

match_id string path required

The match id. Stable across re-imports: what you store today still resolves later. e.g. mt_1JK5QJ9

Returns

data.match_id string

Our id for the match. Stable: what you store today still resolves later.

data.league_id string

Our id for the competition.

data.country_name string

The country the competition belongs to.

data.league_name string

The competition's name.

data.season_start_year integer

The year the season starts in: 2026 for 2026/27.

data.kickoff_utc integer

Kickoff, as a UTC timestamp.

data.kickoff_date string

The kickoff date in UTC, YYYY-MM-DD.

data.kickoff_local_time string

The kickoff time where the match is played, HH:MM.

data.match_status string

Where the match stands: scheduled, in play by half, half time, finished, postponed, cancelled, abandoned, awarded or walkover.

data.home_team_id string

Our id for the home side.

data.home_team_name string

The home side's name.

data.away_team_id string

Our id for the away side.

data.away_team_name string

The away side's name.

data.home_goals integer

The home side's goals: the final score, after extra time where played.

data.away_goals integer

The away side's goals: the final score, after extra time where played.

data.full_time_result empty in this example

home, draw or away, on the final score.

data.half_time_home_goals integer

The home side's goals at half time.

data.half_time_away_goals integer

The away side's goals at half time.

data.half_time_result string

home, draw or away at half time.

data.half_time_source string

Half time source.

data.stoppage_minutes empty in this example

Stoppage time added, in minutes.

data.is_kickoff_rescheduled boolean

Whether the kickoff was moved from its first date or time.

data.home_league_position integer

The home side's place in the table before the match.

data.away_league_position integer

The away side's place in the table before the match.

data.away_travel_km integer

How far the away side travelled, in kilometres.

data.venue_name string

The ground the match was played at.

data.city_name string

The town or city of the ground.

data.latitude number

The ground's latitude.

data.longitude number

The ground's longitude.

data.location_precision string

How exact the ground's position is: the ground itself, or only its town.

data.daylight_minutes integer

Minutes of daylight left at kickoff; negative after dark.

data.sun_elevation_deg number

The sun's height above the horizon at kickoff, in degrees.

data.public_holiday empty in this example

Public holiday.

data.referee_name string

The referee.

data.regular_time_home_goals empty in this example

The home side's goals after 90 minutes.

data.regular_time_away_goals empty in this example

The away side's goals after 90 minutes.

data.regular_time_result empty in this example

home, draw or away after 90 minutes: the result prices settle on.

data.extra_time_home_goals empty in this example

The home side's goals in extra time alone.

data.extra_time_away_goals empty in this example

The away side's goals in extra time alone.

data.shootout_home_goals empty in this example

The home side's penalties scored in the shootout.

data.shootout_away_goals empty in this example

The away side's penalties scored in the shootout.

data.betfair object

Betfair.

data.betfair.home_kickoff_price number

The price for a home win at kickoff, as decimal odds.

data.betfair.draw_kickoff_price number

The price for the draw at kickoff, as decimal odds.

data.betfair.away_kickoff_price number

The price for an away win at kickoff, as decimal odds.

data.betfair.home_half_time_price empty in this example

Home half time price.

data.betfair.matched_kickoff_volume empty in this example

Matched kickoff volume.

data.betfair.market_id empty in this example

Market: our id, stable.

meta.data_as_of string

When the data behind this answer was last brought up to date.

meta.request_id string

This request's id, to quote to support.

Request

curl "https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9" \
  -H "X-API-Key: $FSAPI_KEY"

const res = await fetch("https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9", {
  headers: { "X-API-Key": process.env.FSAPI_KEY }
});
const { data, meta } = await res.json();

import os, requests

r = requests.get(
    "https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9",
    headers={"X-API-Key": os.environ["FSAPI_KEY"]},
)
data = r.json()["data"]

$ch = curl_init("https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: {$key}"],
]);
$data = json_decode(curl_exec($ch), true)["data"];

Example response

A real row from the archive, fetched when this page rendered. Run it against your own key below.

200 OK application/json

{
    "data": {
        "match_id": "mt_28QVFGW",
        "league_id": "lg_3JZKJSZ",
        "country_name": "Colombia",
        "league_name": "Primera A",
        "season_start_year": 2026,
        "kickoff_utc": 1793228400,
        "kickoff_date": "2026-10-28",
        "kickoff_local_time": "23:00",
        "match_status": "finished",
        "home_team_id": "tm_1HXBKY8",
        "home_team_name": "Once Caldas",
        "away_team_id": "tm_2DNYS20",
        "away_team_name": "Alianza Valledupar",
        "home_goals": 1,
        "away_goals": 0,
        "full_time_result": null,
        "half_time_home_goals": 0,
        "half_time_away_goals": 0,
        "half_time_result": "draw",
        "half_time_source": "feed",
        "stoppage_minutes": null,
        "is_kickoff_rescheduled": false,
        "home_league_position": 7,
        "away_league_position": 16,
        "away_travel_km": 650,
        "venue_name": "Estadio Palogrande",
        "city_name": "Manizales",
        "latitude": 5.056233,
        "longitude": -75.489807,
        "location_precision": "ground",
        "daylight_minutes": 717,
        "sun_elevation_deg": -4.6,
        "public_holiday": null,
        "referee_name": "Carlos Alberto Diaz Vargas",
        "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,
        "betfair": {
            "home_kickoff_price": 1.58,
            "draw_kickoff_price": 3.7,
            "away_kickoff_price": 6.25,
            "home_half_time_price": null,
            "matched_kickoff_volume": null,
            "market_id": null
        }
    },
    "meta": {
        "data_as_of": "2026-10-29T04:32:57Z",
        "request_id": "01J9QW3C7M4KX2VB"
    }
}

Run it live

Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.

Your API key Get a key

match_id required

GET

← All endpoints Get a free key →