Use this football API endpoint to retrieve key match events, including goal times, goal scorers, and yellow or red card details. The endpoint supports both live football matches and completed fixtures, making it very useful.
ENDPOINT
To retrieve event data for live football matches or completed matches stored in our historical database, make a request to the URL below. Historical match data is available only when records exist for the selected game. At kickoff, the data array will be empty because no match events have been recorded yet. As the game unfolds, the football API will return newly available events in the response. To fetch events for a specific match, you must provide its id.
Check this Football API endpoint in our postman collection. Download it now!
Parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| lang | String | ar | The two letter code for a language supported by the football API. This parameter is available only with selected subscription packages. | |
| match_id | Number | 1 | 129180 | The id of the football match whose events you want to retrieve using the football API. |
RESPONSE
The football API response provides a breakdown of every recorded match event, together with key details about the match itself. Developers can use a single endpoint to access both event data and match information, simplifying integration into live score apps, match trackers, and football statistics platforms.
| Name | Type | Example | Description |
|---|---|---|---|
| event | String | YELLOW_CARD | The event category, identifying the type of match incident. Refer to the table below for the supported event types and their meanings. |
| info.id | Number | 2961 | The id of the second player involved in the event, typically used to identify the incoming or outgoing player during a substitution. The value may be null if no second player is associated with the event. |
| info.name | String | Marcus Thuram | The name of the second player associated with the event, typically identifying the player who provided an assist for a goal. The value may be null if no assisting player is recorded. |
| is_away | Boolean | false | Indicates whether the event or associated player is linked to the away team. |
| is_home | Boolean | true | Indicates whether the event or associated player belongs to the home team. |
| label | String | Goal | A human readable description of the event, making it easier to identify and display the event type. |
| player.id | Number | 2170 | The id of the player associated with the event. The value may be null if no player is linked to the event. |
| player.name | String | Paul Pogba | The name of the player associated with the match event returned by the football API. |
| sort | Number | 8 | A zero based sequence number that indicates the chronological order of events within a match. The value increases with each event. |
| time | Number | 38 | The match minute indicating when the event took place, measured from kick off. |
{
"success": true,
"data": {
"match": {
"id": "385735",
"date": "2022-12-18",
"time": "AP",
"status": "FINISHED",
"added": "2022-12-18 14:45:12",
"last_changed": "2022-12-18 18:54:06",
"location": "Lusail Stadium, Lusail",
"fixture_id": "1581460",
"scheduled": "15:00",
"odds": {
"pre": {
"1": 2.70000000000000017763568394002504646778106689453125,
"2": 2.87999999999999989341858963598497211933135986328125,
"X": 3.100000000000000088817841970012523233890533447265625
},
"live": {
"1": null,
"2": null,
"X": null
}
},
"outcomes": {
"half_time": "1",
"full_time": "X",
"extra_time": "X",
"penalty_shootout": "1"
},
"scores": {
"score": "3 - 3",
"ht_score": "2 - 0",
"ft_score": "2 - 2",
"et_score": "3 - 3",
"ps_score": "4 - 2"
},
"home": {
"id": 1443,
"name": "Argentina",
"stadium": "Estadio Monumental Antonio Vespucio Liberti",
"country_id": 117,
"logo": "https:\/\/cdn.football-api.com\/teams\/1443.png"
},
"away": {
"id": 1439,
"name": "France",
"stadium": "Stade de France",
"country_id": 115,
"logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
},
"competition": {
"id": 362,
"name": "FIFA World Cup",
"is_league": false,
"is_cup": true,
"tier": 0,
"has_groups": true,
"active": true,
"national_teams_only": true
},
"country": null,
"federation": {
"id": 1,
"name": "FIFA"
}
},
"event": [
{
"id": 370576400,
"player": {
"id": 2170,
"name": "Lionel Messi"
},
"time": 23,
"event": "GOAL",
"sort": 0,
"info": null,
"is_home": true,
"is_away": false,
"label": "Goal"
},
{
"id": 370576401,
"player": {
"id": 13884,
"name": "Angel Di Maria"
},
"time": 36,
"event": "GOAL",
"sort": 1,
"info": {
"id": 3257,
"name": "Alexis MacAllister"
},
"is_home": true,
"is_away": false,
"label": "Goal"
},
{
"id": 370576402,
"player": {
"id": 2961,
"name": "Marcus Thuram"
},
"time": 41,
"event": "SUBSTITUTION",
"sort": 2,
"info": {
"id": 4336,
"name": "Olivier Giroud"
},
"is_home": false,
"is_away": true,
"label": "Substitution"
},
{
"id": 370576403,
"player": {
"id": 31267,
"name": "Randal Kolo Muani"
},
"time": 41,
"event": "SUBSTITUTION",
"sort": 3,
"info": {
"id": 2179,
"name": "Ousmane Dembele"
},
"is_home": false,
"is_away": true,
"label": "Substitution"
},
{
"id": 370576404,
"player": {
"id": 86149,
"name": "Enzo Fernandez"
},
"time": 45,
"event": "YELLOW_CARD",
"sort": 4,
"info": null,
"is_home": true,
"is_away": false,
"label": "Yellow card"
}
]
}
}| Type | Meaning |
|---|---|
| GOAL | A goal has been scored during the match. |
| GOAL_PENALTY | A goal has been scored from a penalty kick. |
| OWN_GOAL | A player has scored an own goal for the opposing team. |
| YELLOW_CARD | The referee has cautioned a player with a yellow card. |
| RED_CARD | The referee has sent a player off with a red card. |
| YELLOW_RED_CARD | A player has received a second yellow card and has been sent off. |
| SUBSTITUTION | A player has entered the pitch to replace a teammate. |
| MISSED_PENALTY | A player has failed to convert a penalty kick. |
CODE EXAMPLES
To retrieve event data for a match with available events, send a request to the football API using the match's id.
cUrl:
curl -XGET "https://api.football-api.com/matches/events.json?key=demo_key&secret=demo_secret&id=385735"file_get_contents('https://api.football-api.com/matches/events.json?key=demo_key\&secret=demo_secret\&id=385735');import urllib2
req = urllib2.Request('https://api.football-api.com/matches/events.json?key=demo_key\&secret=demo_secret\&id=385735')
response = urllib2.urlopen(req)
print response.read()To access translated event data through the football API, you must have a subscription package](/prices) that includes [language support. Without an eligible package, player names are returned in English.
Adding the lang parameter to the request URL enables translations of event labels and other match information into the selected language, provided it is supported by your package.