Getting past matches

On this page you can find the way to use our historical API endpoints. Get the information about past matches that have ended.


This football api endpoint supports filtering by league, but they are now deprecated to get optimal results, please switch to using competitions instead. You can find more about competitions on the football competitions documentation page.
The football history 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 time for which there is available information. The possibilities that you have to filter and traverse our historical football data.


NOTE: The id of the match in the football history api endpoint is the same as the id of the livescore api endpoint. However, this id is different is different that 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

In order to get the list of all historical football matches data from our api the only thing you need to do is the call the url bellow. We are supporting historical data for national leagues, cup matches, international leagues from all over the globe. In this example, we have used the demo api key and secret pair. If you login in, you will see all examples with your own api key and api secret

GET:


Parameters

The history API 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. Except for league and competition_id! You have use only one of them at a time.

NameTypeRequiredExampleDescription
fromdateNo2018-05-15Get past matches from this date onwards.
todateNo2018-05-15Get past matches data until this date included.
league*numberNo8Get past matches data for a certain league with the provided id
competition_idnumberNo16The id of the competition which history football matches we look for
teamnumberNo19The id of the team which past scores you need
pagenumberNo3If there are pages you can go to a specific page using this parameter
langstringNoru2 letter ISO 639-1 language code
* Our football api now transitioned to using competitions and leagues are deprecated

Response

A response to a request will contain in total maximum of 30 past matches data for the provided parameters in the query.

NameTypeExampleDescription
idnumber78the id of the match it is the same as the id of the match when it was available in our livescore endpoints. This ID differs from the fixture id.
datedate2019-07-12The date when the match began in UTC time
home_namestringReal Madrid FCthe name of the home side team
away_namestringFC Barcelonathe name of the away side team
ht_scorestring0 - 0the score of the match when half time was reached
ft_scorestring1 - 1the score of the match when 90 minutes were reached
et_scorestring1 - 2 the score of the match after 120 minutes of extra time
timestringFTthe time in minutes. It should always be FT
league_idnumber5the id of the league to which the game belonged
statusstringFINISHEDthe status of the match it should always be FINISHED
addeddatetime2018-03-23 14:27:02the date and time when the soccer match was added to our livescore api data endpoint
last_changeddatetime2018-03-23 14:27:02 the date and time when the last modification of the match records was made
home_idnumber18the id of the home team, 0 if not availalbe
away_idnumber19the id of the away team, 0 if not available
competition_idnumber16The id of the competition in which the match took place
competition_namestringPremier LeagueThe name of the competition in which the match took place
locationstringOld TraffordThe place where the match takes place, it can be the stadium name, the city name, both, or it can even include the country name
fixture_idnumber123456The 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
scheduledstring12:00The hour and minute for which the match was schedule to start
{
    "success": true,
    "data": {
        "match": [
            {
                "id": "148763",
                "date": "2019-07-12",
                "home_name": "Dnyapro Mogilev",
                "away_name": "Energetik-BGU",
                "score": "3 - 4",
                "ht_score": "2 - 2",
                "ft_score": "3 - 4",
                "et_score": "",
                "time": "FT",
                "league_id": "20",
                "status": "FINISHED",
                "added": "2019-07-12 15:30:06",
                "last_changed": "2019-07-12 17:37:07",
                "home_id": "2119",
                "away_id": "4226",
                "competition_id": "16",
                "competition_name": "Premier",
                "location": "Spartak Stadium, Mogilev",
                "fixture_id": 10523,
                "scheduled": "15:30"
            },
            {
                "id": "148786",
                "date": "2019-07-12",
                "home_name": "FC Minsk",
                "away_name": "Isloch",
                "score": "3 - 3",
                "ht_score": "2 - 1",
                "ft_score": "3 - 3",
                "et_score": "",
                "time": "FT",
                "league_id": "20",
                "status": "FINISHED",
                "added": "2019-07-12 17:30:13",
                "last_changed": "2019-07-12 19:35:08",
                "home_id": "2089",
                "away_id": "2190",
                "competition_id": "16",
                "competition_name": "Premier",
                "location": "FC Minsk Stadium",
                "fixture_id": 1589845,
                "scheduled": "17:30"
            }
        ],
        "next_page": "https:\/\/livescore-api.com\/api-client\/scores\/history.json?key=demo_key&secret=demo_secret&competition_id=16&page=2",
        "prev_page": false
    }
}


Examples

The following examples show you how to use this endpoint in various programming languages without any filters provided. In this example, we have used the demo api key and secret pair. If you login in, you will see all examples with your own api key and api secret

cUrl

curl -XGET http://livescore-api.com/api-client/scores/history.json?key=demo_key\\&secret=demo_secret
PHP
file_get_contents('http://livescore-api.com/api-client/scores/history.json?key=demo_key\&secret=demo_secret');
Python
import urllib2
req = urllib2.Request('http://livescore-api.com/api-client/scores/history.json?key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()