Match

Overview

The Match Resource reflects a scheduled football game. A game belongs to a competition and a season. It owns a stage and is typically played on a certain matchday. As mentioned in the introducing chapters the latter two are only attributes of a match, whereas competition and season are annotated object-like.

Furthermore the resource returns a head2head node at the very top that holds some simple aggregations. If you want more detailed stuff like that, call the Head2head Subresource on that same match (by appending /head2head to the URI).

The list resource appears as subresource for the Competition, Team and Person Resource.

Let’s see the entire beauty of the Match Resource underneath.

curl -XGET 'https://api.football-data.org/v4/matches/330299' -H "X-Auth-Token: UR_TOKEN"
{
    "area": {
        "id": 2081,
        "name": "France",
        "code": "FRA",
        "flag": "https://crests.football-data.org/773.svg"
    },
    "competition": {
        "id": 2015,
        "name": "Ligue 1",
        "code": "FL1",
        "type": "LEAGUE",
        "emblem": "https://crests.football-data.org/FL1.png"
    },
    "season": {
        "id": 746,
        "startDate": "2021-08-06",
        "endDate": "2022-05-21",
        "currentMatchday": 38,
        "winner": null,
        "stages": [
            "REGULAR_SEASON"
        ]
    },
    "id": 330299,
    "utcDate": "2022-02-27T16:05:00Z",
    "status": "FINISHED",
    "minute": 90,
    "injuryTime": 7,
    "attendance": 16871,
    "venue": "Stade de l'Aube",
    "matchday": 26,
    "stage": "REGULAR_SEASON",
    "group": null,
    "lastUpdated": "2022-06-06T08:20:24Z",
    "homeTeam": {
        "id": 531,
        "name": "ES Troyes AC",
        "shortName": "Troyes",
        "tla": "ETR",
        "crest": "https://crests.football-data.org/531.svg",
        "coach": {
            "id": 108988,
            "name": "Bruno Irles",
            "nationality": "France"
        },
        "leagueRank": null,
        "formation": "3-4-1-2",
        "lineup": [
            {
                "id": 899,
                "name": "Gauthier Gallon",
                "position": "Goalkeeper",
                "shirtNumber": 30
            },
            {
                "id": 8775,
                "name": "Yoann Salmier",
                "position": "Centre-Back",
                "shirtNumber": 17
            },
            {
                "id": 8348,
                "name": "Adil Rami",
                "position": "Centre-Back",
                "shirtNumber": 23
            },
            {
                "id": 9004,
                "name": "Erik Palmer-Brown",
                "position": "Centre-Back",
                "shirtNumber": 2
            },
            {
                "id": 123574,
                "name": "Issa Kaboré",
                "position": "Right-Back",
                "shirtNumber": 29
            },
            {
                "id": 37728,
                "name": "Abdu Conté",
                "position": "Left-Back",
                "shirtNumber": 12
            },
            {
                "id": 507,
                "name": "Florian Tardieu",
                "position": "Defensive Midfield",
                "shirtNumber": 10
            },
            {
                "id": 8623,
                "name": "Tristan Dingomé",
                "position": "Central Midfield",
                "shirtNumber": 5
            },
            {
                "id": 43707,
                "name": "Mama Baldé",
                "position": "Right Winger",
                "shirtNumber": 25
            },
            {
                "id": 8415,
                "name": "Rominigue Kouamé",
                "position": "Central Midfield",
                "shirtNumber": 6
            },
            {
                "id": 6406,
                "name": "Iké Ugbo",
                "position": "Centre-Forward",
                "shirtNumber": 13
            }
        ],
        "bench": [
            {
                "id": 74570,
                "name": "Sébastien Rénot",
                "position": "Goalkeeper",
                "shirtNumber": 16
            },
            {
                "id": 99805,
                "name": "Giulian Biancone",
                "position": "Right-Back",
                "shirtNumber": 4
            },
            {
                "id": 811,
                "name": "Youssouf Koné",
                "position": "Left-Back",
                "shirtNumber": 3
            },
            {
                "id": 133766,
                "name": "Yasser Larouci",
                "position": "Left-Back",
                "shirtNumber": 22
            },
            {
                "id": 8544,
                "name": "Dylan Chambost",
                "position": "Attacking Midfield",
                "shirtNumber": 14
            },
            {
                "id": 824,
                "name": "Xavier Chavalerin",
                "position": "Central Midfield",
                "shirtNumber": 24
            },
            {
                "id": 1043,
                "name": "Lebo Mothiba",
                "position": "Centre-Forward",
                "shirtNumber": 26
            },
            {
                "id": 519,
                "name": "Yoann Touzghar",
                "position": "Centre-Forward",
                "shirtNumber": 7
            },
            {
                "id": 169252,
                "name": "Metinho",
                "position": "Central Midfield",
                "shirtNumber": 31
            }
        ],
        "statistics": {
            "corner_kicks": 4,
            "free_kicks": 10,
            "goal_kicks": 5,
            "offsides": 4,
            "fouls": 16,
            "ball_possession": 41,
            "saves": 1,
            "throw_ins": 12,
            "shots": 8,
            "shots_on_goal": 3,
            "shots_off_goal": 5,
            "yellow_cards": 5,
            "yellow_red_cards": 0,
            "red_cards": 0
        }
    },
    "awayTeam": {
        "id": 516,
        "name": "Olympique de Marseille",
        "shortName": "Marseille",
        "tla": "MAR",
        "crest": "https://crests.football-data.org/516.png",
        "coach": {
            "id": 33636,
            "name": "Jorge Sampaoli",
            "nationality": "Argentina"
        },
        "leagueRank": null,
        "formation": "4-3-3",
        "lineup": [
            {
                "id": 32695,
                "name": "Pau López",
                "position": "Goalkeeper",
                "shirtNumber": 16
            },
            {
                "id": 80171,
                "name": "William Saliba",
                "position": "Centre-Back",
                "shirtNumber": 2
            },
            {
                "id": 10206,
                "name": "Duje Ćaleta-Car",
                "position": "Centre-Back",
                "shirtNumber": 15
            },
            {
                "id": 8346,
                "name": "Boubacar Kamara",
                "position": "Defensive Midfield",
                "shirtNumber": 4
            },
            {
                "id": 8695,
                "name": "Valentin Rongier",
                "position": "Central Midfield",
                "shirtNumber": 21
            },
            {
                "id": 1086,
                "name": "Luan Peres",
                "position": "Centre-Back",
                "shirtNumber": 14
            },
            {
                "id": 1815,
                "name": "Gerson",
                "position": "Central Midfield",
                "shirtNumber": 8
            },
            {
                "id": 600,
                "name": "Mattéo Guendouzi",
                "position": "Central Midfield",
                "shirtNumber": 6
            },
            {
                "id": 1818,
                "name": "Cengiz Ünder",
                "position": "Right Winger",
                "shirtNumber": 17
            },
            {
                "id": 8360,
                "name": "Dimitri Payet",
                "position": "Attacking Midfield",
                "shirtNumber": 10
            },
            {
                "id": 166640,
                "name": "Ahmadou Bamba Dieng",
                "position": null,
                "shirtNumber": 12
            }
        ],
        "bench": [
            {
                "id": 3356,
                "name": "Steve Mandanda",
                "position": "Goalkeeper",
                "shirtNumber": 30
            },
            {
                "id": 33108,
                "name": "Álvaro González",
                "position": "Centre-Back",
                "shirtNumber": 3
            },
            {
                "id": 7786,
                "name": "Sead Kolašinac",
                "position": "Left-Back",
                "shirtNumber": 23
            },
            {
                "id": 3714,
                "name": "Amine Harit",
                "position": "Attacking Midfield",
                "shirtNumber": 7
            },
            {
                "id": 633,
                "name": "Pape Gueye",
                "position": "Defensive Midfield",
                "shirtNumber": 22
            },
            {
                "id": 2105,
                "name": "Arkadiusz Milik",
                "position": "Centre-Forward",
                "shirtNumber": 9
            },
            {
                "id": 115074,
                "name": "Luis Henrique",
                "position": "Left Winger",
                "shirtNumber": 11
            },
            {
                "id": 21583,
                "name": "Cédric Bakambu",
                "position": "Centre-Forward",
                "shirtNumber": 13
            },
            {
                "id": 166642,
                "name": "Pol Lirola",
                "position": null,
                "shirtNumber": 29
            }
        ],
        "statistics": {
            "corner_kicks": 8,
            "free_kicks": 20,
            "goal_kicks": 7,
            "offsides": 0,
            "fouls": 10,
            "ball_possession": 59,
            "saves": 2,
            "throw_ins": 14,
            "shots": 4,
            "shots_on_goal": 2,
            "shots_off_goal": 2,
            "yellow_cards": 3,
            "yellow_red_cards": 0,
            "red_cards": 0
        }
    },
    "score": {
        "winner": "DRAW",
        "duration": "REGULAR",
        "fullTime": {
            "home": 1,
            "away": 1
        },
        "halfTime": {
            "home": 0,
            "away": 1
        }
    },
    "goals": [
        {
            "minute": 28,
            "injuryTime": null,
            "type": "PENALTY",
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "scorer": {
                "id": 8360,
                "name": "Dimitri Payet"
            },
            "assist": null,
            "score": {
                "home": 0,
                "away": 1
            }
        },
        {
            "minute": 90,
            "injuryTime": null,
            "type": "REGULAR",
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "scorer": {
                "id": 519,
                "name": "Yoann Touzghar"
            },
            "assist": {
                "id": 811,
                "name": "Youssouf Koné"
            },
            "score": {
                "home": 1,
                "away": 1
            }
        }
    ],
    "penalties": [
        {
            "player": {
                "id": 8360,
                "name": "Dimitri Payet"
            },
            "team": {
                "id": null,
                "name": null
            },
            "scored": true
        }
    ],
    "bookings": [
        {
            "minute": 11,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "player": {
                "id": 8695,
                "name": "Valentin Rongier"
            },
            "card": "YELLOW"
        },
        {
            "minute": 27,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "player": {
                "id": 43707,
                "name": "Mama Baldé"
            },
            "card": "YELLOW"
        },
        {
            "minute": 36,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "player": {
                "id": 507,
                "name": "Florian Tardieu"
            },
            "card": "YELLOW"
        },
        {
            "minute": 36,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "player": {
                "id": 8348,
                "name": "Adil Rami"
            },
            "card": "YELLOW"
        },
        {
            "minute": 49,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "player": {
                "id": 37728,
                "name": "Abdu Conté"
            },
            "card": "YELLOW"
        },
        {
            "minute": 55,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "player": {
                "id": 8360,
                "name": "Dimitri Payet"
            },
            "card": "YELLOW"
        },
        {
            "minute": 85,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "player": {
                "id": 32695,
                "name": "Pau López"
            },
            "card": "YELLOW"
        },
        {
            "minute": 90,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "player": {
                "id": 99805,
                "name": "Giulian Biancone"
            },
            "card": "YELLOW"
        }
    ],
    "substitutions": [
        {
            "minute": 57,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "playerOut": {
                "id": 8695,
                "name": "Valentin Rongier"
            },
            "playerIn": {
                "id": 166642,
                "name": "Pol Lirola"
            }
        },
        {
            "minute": 57,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "playerOut": {
                "id": 166640,
                "name": "Ahmadou Bamba Dieng"
            },
            "playerIn": {
                "id": 115074,
                "name": "Luis Henrique"
            }
        },
        {
            "minute": 58,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "playerOut": {
                "id": 6406,
                "name": "Iké Ugbo"
            },
            "playerIn": {
                "id": 1043,
                "name": "Lebo Mothiba"
            }
        },
        {
            "minute": 59,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "playerOut": {
                "id": 37728,
                "name": "Abdu Conté"
            },
            "playerIn": {
                "id": 811,
                "name": "Youssouf Koné"
            }
        },
        {
            "minute": 77,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "playerOut": {
                "id": 9004,
                "name": "Erik Palmer-Brown"
            },
            "playerIn": {
                "id": 99805,
                "name": "Giulian Biancone"
            }
        },
        {
            "minute": 77,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "playerOut": {
                "id": 43707,
                "name": "Mama Baldé"
            },
            "playerIn": {
                "id": 519,
                "name": "Yoann Touzghar"
            }
        },
        {
            "minute": 78,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "playerOut": {
                "id": 8360,
                "name": "Dimitri Payet"
            },
            "playerIn": {
                "id": 2105,
                "name": "Arkadiusz Milik"
            }
        },
        {
            "minute": 86,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "playerOut": {
                "id": 1818,
                "name": "Cengiz Ünder"
            },
            "playerIn": {
                "id": 633,
                "name": "Pape Gueye"
            }
        },
        {
            "minute": 87,
            "team": {
                "id": 516,
                "name": "Olympique de Marseille"
            },
            "playerOut": {
                "id": 1086,
                "name": "Luan Peres"
            },
            "playerIn": {
                "id": 7786,
                "name": "Sead Kolašinac"
            }
        },
        {
            "minute": 90,
            "team": {
                "id": 531,
                "name": "ES Troyes AC"
            },
            "playerOut": {
                "id": 8415,
                "name": "Rominigue Kouamé"
            },
            "playerIn": {
                "id": 824,
                "name": "Xavier Chavalerin"
            }
        }
    ],
    "odds": {
        "homeWin": 4.25,
        "draw": 3.72,
        "awayWin": 1.81
    },
    "referees": [
        {
            "id": 57080,
            "name": "Cyril Mugnier",
            "type": "ASSISTANT_REFEREE_N1",
            "nationality": "France"
        },
        {
            "id": 57049,
            "name": "Mehdi Rahmouni",
            "type": "ASSISTANT_REFEREE_N2",
            "nationality": "France"
        },
        {
            "id": 57031,
            "name": "Alexandre Perreau Niel",
            "type": "FOURTH_OFFICIAL",
            "nationality": "France"
        },
        {
            "id": 43918,
            "name": "François Letexier",
            "type": "REFEREE",
            "nationality": "France"
        },
        {
            "id": 57073,
            "name": "Jérémie Pignard",
            "type": "VIDEO_ASSISTANT_REFEREE_N1",
            "nationality": "France"
        },
        {
            "id": 166622,
            "name": "Abdelali Chaoui",
            "type": "VIDEO_ASSISTANT_REFEREE_N2",
            "nationality": null
        }
    ]
}

Available filters for the list resource

Filter name Possible values Sample Description

ids

A list of integers, like [\d]{4}

/?ids=333,3303,3213

lists 3 matches with the given ids

date

A date in format yyyy-MM-dd

/?date=2022-01-01

Lists all matches for the given date

dateFrom

A date in format yyyy-MM-dd

/?dateFrom=2022-01-01

Must be used in conjunction with dateTo

dateTo

A date in format yyyy-MM-dd

/?dateTo=2022-01-10

Lists all matches before the given date until and including dateFrom

status

Status enum

/?status=FINISHED

only lists finished matches for the current day

Status workflow explained

The status field indicates the current phase a match is in. For the majority this is FINISHED (96,9% of all matches in my database contain that status) but how do matches get there? Lets try to depict that with a diagram. The slightly greenish boxes show the "happy flow".

match status v4

As soon as a match finds it’s way to the database and given there is a rough date set, it is stamped with status SCHEDULED. As soon the date is finalised with an exact date and time, the match enters status TIMED. It gets played (IN_PLAY), the players rest (PAUSED) and the final whistle pushes the match to FINISHED.

The grey box shows the 'pseudo-status' LIVE, that you can use as a match filter. It’s just for convenience, so in the end it combines status IN_PLAY and PAUSED (and the backend does exactly that if you pass LIVE as value for status).

Last but not least not all the time everything goes well, but I won’t go into detail here as I think everything is quite clear within the diagram.

Enums

Some fields contain values that are defined by an Enum, which is useful to reveal, so here we go:

Attribute name Possible values

status

SCHEDULED, TIMED, IN_PLAY, PAUSED, FINISHED, SUSPENDED, POSTPONED, CANCELLED, AWARDED

stage

FINAL | THIRD_PLACE | SEMI_FINALS | QUARTER_FINALS | LAST_16 | LAST_32 | LAST_64 | ROUND_4 | ROUND_3 | ROUND_2 | ROUND_1 | GROUP_STAGE | PRELIMINARY_ROUND | QUALIFICATION | QUALIFICATION_ROUND_1 | QUALIFICATION_ROUND_2 | QUALIFICATION_ROUND_3 | PLAYOFF_ROUND_1 | PLAYOFF_ROUND_2 | PLAYOFFS | REGULAR_SEASON | CLAUSURA | APERTURA | CHAMPIONSHIP_ROUND | RELEGATION_ROUND

group

GROUP_A | GROUP_B | GROUP_C | GROUP_D | GROUP_E | GROUP_F | GROUP_G | GROUP_H | GROUP_I | GROUP_J | GROUP_K | GROUP_L