Get a match

Fetch one match in full: teams, kickoff, a detailed score breakdown with the half-time score, the venue, the referee and both managers. Use it for a match page, or to check which extra data (odds, xG, shot map) exists before you call those endpoints.

curl "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i" \
  -H "X-Api-Key: $SOCCER_DATA_KEY"

const res = await fetch("https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i",
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i')
    ->json('data');

{
    "data": {
        "id": "match_9pd0ck6g2m9i",
        "competition_id": "competition_705uv6jm8myn",
        "competition_name": "Premier League",
        "season_id": "season_98l95mxugqs9",
        "matchday": 37,
        "stage": "regular",
        "stage_name": null,
        "group_label": null,
        "status": "finished",
        "utc_date": "2026-05-15T19:00:00.000Z",
        "home_team": {
            "id": "team_4mimn5fmya2v",
            "name": "Aston Villa"
        },
        "away_team": {
            "id": "team_74p8tg2k93z4",
            "name": "Liverpool"
        },
        "score": {
            "home": 4,
            "away": 2,
            "final_score": null,
            "regulation": {
                "home": 4,
                "away": 2
            },
            "after_extra_time": null,
            "penalty_shootout": null,
            "went_to_extra_time": false,
            "went_to_penalties": false,
            "winner": "home",
            "half_time_home": 1,
            "half_time_away": 0
        },
        "venue": {
            "name": "Villa Park",
            "city": "Birmingham"
        },
        "is_neutral": false,
        "referee": {
            "id": "referee_o1sm9am51qq5",
            "name": "Chris Kavanagh"
        },
        "home_manager": {
            "id": "manager_17xiheuxdn67",
            "name": "Unai Emery"
        },
        "away_manager": {
            "id": "manager_fzvvh82pzed4",
            "name": "Arne Slot"
        },
        "odds_available": true,
        "live_odds_available": false,
        "xg_available": true,
        "shotmap_available": true,
        "xg_quality": "full"
    }
}

### GET /matches/{match_id}

Get a match

Fetch one match in full: teams, kickoff, a detailed score breakdown with the half-time score, the venue, the referee and both managers. Use it for a match page, or to check which extra data (odds, xG, shot map) exists before you call those endpoints.
- Check odds_available, xg_available and shotmap_available first, so you don't spend requests on data that isn't there.
- shotmap_available can be false even when xg_available is true.
- Score breakdown fields stay null until the match is finished.
- This endpoint has no live clock. For the in-play minute, use List matches with status=live or the live stats endpoint.
- While a match is live, responses are normally at most 5 minutes old on Free and 15 seconds old on Pro and Business. If a fresh answer can't be fetched, you may get an older copy marked X-Cache: STALE instead: see [When an answer is stale](/docs/concepts/rate-limits#when-an-answer-is-stale).
- An unknown match id returns 404 NOT_FOUND.

Response fields:
- `data.id` (string): The match's id.
- `data.competition_id` (string): The competition this match belongs to.
- `data.competition_name` (string): The competition's name, so you don't need a second call to show it.
- `data.season_id` (string): The season this match belongs to.
- `data.matchday` (integer|null): League round number. Null for cup and knockout fixtures. On play-off fixtures it is the play-off round number, not a league gameweek.
- `data.stage` (string): regular for league and group games, playoff for knockout, cup and promotion or relegation play-off fixtures.
- `data.stage_name` (string|null): Name of the round for cup games, such as final, semi_final or group_stage. Null for normal league games.
- `data.group_label` (string|null): Group letter (A to L) for group-stage games in some tournaments. Null otherwise.
- `data.status` (string): Where the match stands: scheduled, live, finished, postponed or cancelled.
- `data.utc_date` (string): Kickoff time in UTC, as an ISO 8601 date-time.
- `data.home_team.id` (string): Home team's id.
- `data.home_team.name` (string): Home team's name.
- `data.away_team.id` (string): Away team's id.
- `data.away_team.name` (string): Away team's name.
- `data.score.home` (integer|null): Home goals in normal time. Null if the match hasn't been played.
- `data.score.away` (integer|null): Away goals in normal time. Null if the match hasn't been played.
- `data.score.final_score` (object|null): Final score with home and away, included only when it differs from the normal-time score (for example after a shoot-out).
- `data.score.regulation` (object|null): Score after 90 minutes, with home and away. Null until the match is finished.
- `data.score.after_extra_time` (object|null): Goals after 120 minutes, with home and away. Null if there was no extra time.
- `data.score.penalty_shootout` (object|null): Penalties scored by each side in a shoot-out, with home and away. Null if the match wasn't settled on penalties.
- `data.score.went_to_extra_time` (boolean|null): Whether extra time was played. False for formats that go straight to penalties. Null until finished, or when we can't confirm it.
- `data.score.went_to_penalties` (boolean|null): Whether the match was decided by a shoot-out. Null until finished.
- `data.score.winner` (string|null): home, away or draw, taking extra time and penalties into account. Null until finished.
- `data.score.half_time_home` (integer|null): Home goals at half-time.
- `data.score.half_time_away` (integer|null): Away goals at half-time.
- `data.venue` (object|null): Where the match is played. Null for cancelled matches that never had a venue.
- `data.venue.name` (string): Stadium name.
- `data.venue.city` (string): City the stadium is in.
- `data.is_neutral` (boolean|null): True when the match is played at neither team's home ground. Null means we don't know, so don't treat it as false.
- `data.referee` (object|null): The match referee. For career totals, use the match referee endpoint.
- `data.referee.id` (string): Referee's id.
- `data.referee.name` (string): Referee's name.
- `data.home_manager` (object|null): Home team's manager. Can be null.
- `data.home_manager.id` (string): Manager's id.
- `data.home_manager.name` (string): Manager's name.
- `data.away_manager` (object|null): Away team's manager. Can be null.
- `data.away_manager.id` (string): Manager's id.
- `data.away_manager.name` (string): Manager's name.
- `data.odds_available` (boolean): True when pre-match odds exist. Older matches usually only have closing prices.
- `data.live_odds_available` (boolean): True when in-play odds are available right now.
- `data.xg_available` (boolean): True when match-level expected goals (xG) exist.
- `data.shotmap_available` (boolean): True only when the shot map has at least one shot with an xG above zero.
- `data.xg_quality` (string): full when per-shot xG values exist, none when they don't. Treat any value you don't recognise as none.

Example: curl "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i" -H "X-Api-Key: $SOCCER_DATA_KEY"