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.
If you need detailed information about former encounters between the teams, you can call the Head2head Subresource
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".
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 |