This guide explains how to retrieve detailed match statistics using our football API.
null, or the statistics section may be omitted from the response entirely.Match statistics are an essential feature of any football platform, from websites and mobile applications to television and radio broadcasts. They help fans evaluate team performance, compare both sides, and assess how a game may develop while it is in progress. With our head to head football API endpoint, you can analyze the two teams before kickoff. The match statistics football API endpoint lets you track their performance and compare key metrics as the game is live. This makes it a valuable addition to our API service for developers building football related products.
Endpoint
To retrieve match statistics from the football API, you only need the match_id obtained through the livescore api endpoint or the historical matches API endpoint. Statistics become available once the match has kicked off, so this endpoint cannot return statistics for upcoming fixtures retrieved through the fixtures API endpoint.
Check this Football API endpoint in our postman collection. Download it now!
In the example above, the football API returns match statistics for the Real Madrid versus Bayern Munich match. The response contains a list of available statistics for both teams in the match, formatted as a JSON object. Below, we explain the response structure and the meaning of each field, starting with the parameters table, which includes just one entry. You can also include the lang parameter in your request to translate statistic names into your chosen language.
Parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| lang | string | fr | The language in which you want the match statistics to be returned by the football API. | |
| match_id | number | 1 | 172252 | The id of the match for which you want to retrieve statistics. |
Response
The response from the match statistics football API endpoint is simple, with each statistic represented as an individual object within the data array. Every object contains four fields: type, label, home, and away.
The type field identifies the statistic and remains consistent across languages. The label field provides its display name, translated according to the selected language when the lang parameter is supplied, or shown in English when it is omitted. The home and away fields contain the corresponding statistical values for the home and away teams.
For yellow and red cards, this endpoint returns only the total number of cards for each team. To find out which players received them, use the match events API endpoint.
{
"success": true,
"data": [
{
"type": "attacks",
"label": "Attacks",
"home": 0,
"away": 0
},
{
"type": "attempts_on_goal",
"label": "Attempts on Goal",
"home": 21,
"away": 12
},
{
"type": "corners",
"label": "Corners",
"home": 9,
"away": 2
},
{
"type": "dangerous_attacks",
"label": "Dangerous Attacks",
"home": 0,
"away": 0
},
{
"type": "fauls",
"label": "Fouls",
"home": 10,
"away": 12
},
{
"type": "free_kicks",
"label": "Free Kicks",
"home": 0,
"away": 0
},
{
"type": "goal_kicks",
"label": "Goal Kicks",
"home": 0,
"away": 0
},
{
"type": "offsides",
"label": "Offsides",
"home": 2,
"away": 1
},
{
"type": "penalties",
"label": "Penalties",
"home": 0,
"away": 0
},
{
"type": "possesion",
"label": "Possession",
"home": 69,
"away": 31
},
{
"type": "red_cards",
"label": "Red Cards",
"home": 0,
"away": 2
},
{
"type": "saves",
"label": "Saves",
"home": 2,
"away": 4
},
{
"type": "shots_blocked",
"label": "Shots Blocked",
"home": 8,
"away": 3
},
{
"type": "shots_off_target",
"label": "Shots off Target",
"home": 5,
"away": 4
},
{
"type": "shots_on_target",
"label": "Shots on Target",
"home": 9,
"away": 5
},
{
"type": "substitutions",
"label": "Substitutions",
"home": 0,
"away": 0
},
{
"type": "throw_ins",
"label": "Throw Ins",
"home": 0,
"away": 0
},
{
"type": "treatments",
"label": "Treatments",
"home": 0,
"away": 0
},
{
"type": "yellow_cards",
"label": "Yellow Cards",
"home": 1,
"away": 6
}
]
}| Name | Type | Example | Description |
|---|---|---|---|
| away | number | 2 | The statistical value recorded for the away team. |
| home | number | 1 | The statistical value recorded for the home team. |
| label | string | Corners | The display name of the statistic, ready to use directly in an application or website interface. The football API returns this label in the language selected through the lang parameter. |
| type | string | corners | The statistic category identified by this string. |
Translated match statistics
To retrieve match statistics in Danish using the football API, for example: cUrl:
curl -XGET "https://api.football-api.com/statistics/matches.json?key=demo_key&secret=demo_secret&match_id=702913&lang=da"
PHP:
file_get_contents('https://api.football-api.com/statistics/matches.json?key=demo_key\&secret=demo_secret\&match_id=702913\&lang=da');
Python:
import urllib2
req = urllib2.Request('https://api.football-api.com/matches/statistics.json?key=demo_key\&secret=demo_secret\&match_id=702913\&lang=da')
response = urllib2.urlopen(req)
print response.read()