History
On this page, you can find how to use our historical API endpoint and get the information about past matches that have ended.
The history football API endpoint supports teams names in various languages. To find out more about this, read through our documentation on language support.
On this page, we are explaining how you can get the list with football matches and scores that have been played back in time for which there is available information. Also, the possibilities that you have to filter and traverse our historical football data. The matches are ordered in a descending order from the latest finished match to the earliest back in history.
NOTE: the id of the match in the history football API endpoint is the same as the id of the live scores API endpoint. However, this id is different than the id from the football fixtures API endpoint. That is why here we have the fixture_id field to make the connection between a fixture and a match that has finished. If the fixture_id value is empty or 0 this means that there was no fixture for this match before it started.
ENDPOINT
To get the list of all historical football match data from our API, you only need to call the URL below. We support historical data for 400+ national competitions, cup matches, and international leagues from all over the globe.
GET:
PARAMETERS
The football API history endpoint supports several parameters that you can use to filter the football data and traverse through it at your convenience. The parameters are listed in the table below. You can use the parameters together as well as separately.
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| competition_id | number|string | 1,2 | The id of the competition which history football matches we look for. You can the id of the competition from the competition list API endpoint or from our competitions coverage page. You can filter by multiple competitions when you separate their ids with commas. | |
| from | date | 2018-05-15 | Get past matches from this date onwards. | |
| lang | string | ru | 2 letter ISO 639-1 language code. You can find the list of supported languages on our data languages documentation page | |
| page | number | 3 | If there are pages you can go to a specific page using this parameter | |
| team_id | number | 19,7 | The id of the team which past scores you need. If you want you can filter by multiple teams ids separated by commas. | |
| to | date | 2018-05-15 | Get past matches data until this date included. |
RESPONSE
A response to a request will contain in total maximum of 30 past matches data for the provided parameters in the query.
{
"success": true,
"data": {
"match": [
{
"federation": {
"id": 6,
"name": "CONMEBOL"
},
"competition": {
"is_cup": true,
"tier": 0,
"id": 330,
"is_league": false,
"has_groups": true,
"national_teams_only": false,
"active": true,
"name": "Copa Sudamericana"
},
"added": "2024-05-29 00:16:09",
"time": "FT",
"id": 532354,
"fixture_id": 1688522,
"group_id": 3353,
"scheduled": "00:30",
"odds": {
"pre": {
"1": 1.44,
"2": 8,
"X": 4.33
},
"live": {
"1": 501,
"2": 1.04,
"X": 13
}
},
"country": null,
"status": "FINISHED",
"away": {
"stadium": "Estadio Julio C\u00e9sar Villagra",
"logo": "https:\/\/cdn.live-score-api.com\/teams\/08214faa41f5e30135a473ecaa51813e.png",
"id": 451,
"country_id": 65,
"name": "Belgrano Cordoba"
},
"last_changed": "2024-05-29 04:32:07",
"date": "2024-05-29",
"round": "6",
"location": "Est\u00e1dio Jos\u00e9 Pinheiro Borda",
"home": {
"stadium": "Est\u00e1dio Jos\u00e9 Pinheiro Borda",
"logo": "https:\/\/cdn.live-score-api.com\/teams\/afa7f341a383ee79e8b91dae5b0248be.png",
"id": 2416,
"country_id": 16,
"name": "Internacional"
},
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null,
"penalty_shootout": null
},
"scores": {
"score": "1 - 2",
"ht_score": "1 - 2",
"ft_score": "1 - 2",
"et_score": "",
"ps_score": ""
},
"urls": {
"events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?id=532354",
"statistics": "https:\/\/livescore-api.com\/api-client\/matches\/stats.json?match_id=532354",
"lineups": "https:\/\/livescore-api.com\/api-client\/matches\/lineups.json?match_id=532354",
"head2head": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?team1_id=2416&team2_id=451"
}
},
{
"federation": null,
"competition": {
"is_cup": false,
"tier": 2,
"id": 265,
"is_league": true,
"has_groups": true,
"national_teams_only": false,
"active": true,
"name": "Primera B"
},
"added": "2024-05-29 00:16:07",
"time": "FT",
"id": 532352,
"fixture_id": 1695817,
"group_id": null,
"scheduled": "00:30",
"odds": {
"pre": {
"1": 1.9,
"2": 4.2,
"X": 3.3
},
"live": {
"1": 1.06,
"2": 34,
"X": 10
}
},
"country": {
"flag": "COL.png",
"id": 61,
"fifa_code": "COL",
"uefa_code": "",
"name": "Colombia",
"is_real": true
},
"status": "FINISHED",
"away": {
"stadium": "Estadio Guillermo Plazas Alcid",
"logo": "https:\/\/cdn.live-score-api.com\/teams\/f04524d921db2b6ef46aeab633db48d7.png",
"id": 1578,
"country_id": 61,
"name": "Atletico Huila"
},
"last_changed": "2024-05-29 04:53:05",
"date": "2024-05-29",
"round": "3",
"location": "Estadio Ol\u00edmpico Jaime Mor\u00f3n Le\u00f3n",
"home": {
"stadium": "Estadio Ol\u00edmpico Jaime Mor\u00f3n Le\u00f3n",
"logo": "https:\/\/cdn.live-score-api.com\/teams\/205c9f868365f87da2b21d2ca96949a5.png",
"id": 4058,
"country_id": 61,
"name": "Real Cartagena"
},
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null,
"penalty_shootout": null
},
"scores": {
"score": "2 - 0",
"ht_score": "0 - 0",
"ft_score": "2 - 0",
"et_score": "",
"ps_score": ""
},
"urls": {
"events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?id=532352",
"statistics": "https:\/\/livescore-api.com\/api-client\/matches\/stats.json?match_id=532352",
"lineups": "https:\/\/livescore-api.com\/api-client\/matches\/lineups.json?match_id=532352",
"head2head": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?team1_id=4058&team2_id=1578"
}
}
]
}
}| Name | Type | Example | Description |
|---|---|---|---|
| added | string | 2023-12-18 07:45:06 | The date and time of when the match was added to our live-score api feed. |
| away | object | {} | An object holding the information about the away team in the match. It has the structure of our standard team object. |
| competition | object | {} | An object holding the information about the competition in which the match is being played. It has the structure of our standard competition object. |
| country | object | {} | An object holding the information about the country in which the match is being played. It has the structure of our standard country object. If the match is part of an international competition like the UEFA Champions League, the value of the country will be null. |
| date | date | 2018-05-15 | The date when the match began in UTC |
| federation | object | {} | An object holding the information about the federation in which the match is being played. It has the structure of our standard federation object. If the match is part of an national competition like the English Premier League the value of the federation will be null. |
| fixture_id | number | 1657338 | The id of the fixture for which the match is, it could be empty 0 or null, in this case there was no fixture added before the match started |
| group_id | number | 3353 | The id of the group from which the match was. This is the same group ID used in the competition standings API endpoint and the group standings API endpoint. The list of the groups in a competition can obtained from the dedicated API endpoint. |
| home | object | {} | An object holding the information about the home team in the match. It has the structure of our standard team object. |
| id | number | 483252 | The id of the match, this is not the fixture id |
| last_changed | datetime | 2023-12-18 08:42:53 | The date and the time in UTC when the data of the match was last updated. As the match progresses this value will be change often. When the match enters the FINISHED status or the HALF TIME BREAK status it will change less often, since there is not match going on. |
| location | string | Campbelltown Stadium | The place where the match takes place, it can be the stadium name, the city name, both, or it can even include the country name |
| odds | object | {} | An object that holds information about the pre match and live match betting odds. It has the structure of a standard odds object |
| outcomes | object | {} | An object that holds information about the betting outcomes (1, X, 2) on the different match periods. It has the structure of a standard outcomes object |
| round | string | QF | The round of the competition in which the match occurred could be a number like 1, 2, 3 or an abbreviation for knockout stages: R16, QF, SF, F |
| scheduled | string | 08:00 | The hour and minute for which the match was schedule to start in UTC |
| scores | object | {} | An object that holds information about the score lines at the end of the different match periods. It has the structure of a standard scores object |
| status | string | IN PLAY | the status of the game: FINISHED |
| time | string | 43 | The value of time can be one of the 3 following options:FT - Means that the 90 minutes have finishedAET - Means that the 120 minutes have finishedAP - Means that the penalty shootout has finished. |
| urls | object | {} | An object with various links to detailed information about the match. It has the structure of a urls object. In the case of the live score API endpoint the urls object has 4 keys: events - a link to the match events data API endpoint statistics - A link to the match statistics API endpointlineups - A link to the API endpoint with the match lineup players information head2head - A link to the H2H team comparison API endpoint that will compare the 2 teams participating in the match. |
EXAMPLES
The following examples show you how to use this endpoint in various programming languages with a competition_id provided as a filter.
cUrl:
curl -XGET "https://livescore-api.com/api-client/matches/history.json?key=demo_key&secret=demo_secret&competition_id=4"file_get_contents('https://livescore-api.com/api-client/history/live.json?key=demo_key\&secret=demo_secret\&competition_id=4');import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/matches/history.json?key=demo_key\&secret=demo_secret\&competition_id=4')
response = urllib2.urlopen(req)
print response.read()