Getting live-scores

In this reference page, we explain how you can obtain the score of the matches that are being currently played.

This API Endpoint will provide matches only if they are being played right now. E.g. Live If you want to get matches that have finished please use our history endpoints. To learn more follow our Football database documentation link.

This live-score api endpoint supports teams names in various languages. To find out more about this. Read through our documentation on language support.

NOTE: In our soccer API, when it comes to matches we are using 2 different types of IDs to operate with football matches. First, its the fixture id, it is solely for the purpose of keeping track of scheduled matches that we have. The fixture id is different than the match id, which is the second ID that we use. Every match gets an ID when it gets into our database. Once the match is over and it goes into the history database this match id persists and remains the same. The fixture id and match id for the same match are totally different. That's why we have the fixture_id field both in the live-score api endpoint and in the history api endpoint.

Endpoint

There are 3 options when retrieving the current live-scores. You can get the list of all matches using the explanation in the first section of this page. To get the scores for a certain competition or certain country only, you will need to provide the ids of the country or competition. This functionality is explained in the second and third parts of this reference.

In order to get the live-scores of currently played football matches, the only thing you need to do is the call the url bellow. Once a game is over it will stay in the live-score feed until 3 hours after the game has begun. For example, if the game ended in 90 minutes it will be available in the feed with a status of FINISHED for another hour and 15 minutes. If there is extra time, the game will be available for 45 minutes more after the extra time has been played out. 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 live-scores api endpoint supports several parameters that help you filter matches based on countries or competitions. There is also a parameter that allow you to translate some of the data in different languages.

Name	Type	Required	Example	Description
country	number	optional	1	Filters the matches by country in which they are played, or the general competition in case of Champions league
lang	string	optional	ar	2 letter ISO 639-1 language code
competition_id	number	optional	16	Filters the scores by the competition in which they take place

* Our soccer API is now transitioned to using competitions and leagues are deprecated

Reponse

The response contains the following information, for every match element in the list. The same rules apply for the JSON objects.

Name	Type	Example	Description
id	number	49	the id of the match
home_name	string	Man United	the name of the home team.
away_name	string	Man City	the name of the away team.
score	string	2 - 0	contains the latest score of the game. Depending on how the game progress this will be the field that will give you the most up to date score. If the game goes in extra time and there are goals scored this field will reflect that. If you need only the 90 minutes scores you can use the `ft_score` field.
ht_score	string	2 - 0	contains the half time score of the game if the half time has been reached.
ft_score	string	2 - 0	contains the full time score of the game if the full time has been reached.
et_score	string	2 - 0	contains the extra time score of the game if the extra time has been reached.
time	integer	67	the number minutes that have passed since the beginning of the game.
league_id	integer	5	the id of the league to which the game belongs.
league_name	string	Premier League	the name of the league to which the game belongs to.
added	datetime	2018-03-23 14:27:02	contains a date time of when the match was added to our live-score api feed.
last_changed	datetime	2018-03-23 14:27:02	contains a date time of when the match data was checked or updated.
status	string	NOT STARTED	the status of the game. The possible statuses that you can see are: `NOT STARTED` - The has not started yet, but it is about to start. `IN PLAY` - The match is in play. `HALF TIME BREAK` - The half time break is currently ongoing. `ADDED TIME` - The soccer game is in added time of the first half or second half. This status is not to be confused with extra time when a winner could not be decided in regular time. `FINISHED` - The game has finished its regular 2 halves of 30 minutes. `INSUFFICIENT DATA` - Due to problems we cannot provide you with accurate data, but the game is underway.
home_id	integer	19	as we are building our team database with teams and their ids for some matches there will be a team id provided for the home team
away_id	integer	12	as we are building our team database with teams and their ids for some matches there will be a team id provided for the away team
events	string	url,boolean	this functionality is currently in beta testing. If we do not have the possibility to provide the events right now the value of this field will be `false` (This could be caused by the fact that we will not provide events at all, or currently there are no events that have happened). In the cases where we do have the events the value of the field will be a link to the API endpoint that will give you the list of the events that have happened in the event. To read more about the live match events you can follow this link.
competition_id	number	16	The id of the competition in which the match takes places
competition_name	string	Premier	The name of the football competition in which the match takes places
location	string	Old Trafford	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
fixture_id	number	123456	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
scheduled	string	12:00	The hour and minute for which the match was schedule to start

{
    "success": true,
    "data": {
        "match": [
            {
                "competition_id": 370,
                "status": "IN PLAY",
                "ht_score": "",
                "ft_score": "",
                "et_score": "",
                "last_changed": "2019-07-19 14:14:05",
                "id": 149525,
                "league_name": "Club Friendlies",
                "away_id": 499,
                "score": "0 - 2",
                "competition_name": "Club Friendlies",
                "events": false,
                "home_id": 0,
                "away_name": "Bristol City",
                "added": "2019-07-19 12:45:04",
                "time": "37",
                "home_name": "Sarasota Metropolis FC",
                "league_id": 5,
                "location": "IMG Academy Bradenton, Florida",
                "fixture_id": 5,
                "scheduled": "14:00"
            },
            {
                "competition_id": 29,
                "status": "FINISHED",
                "ht_score": "1 - 2",
                "ft_score": "3 - 3",
                "et_score": "",
                "last_changed": "2019-07-19 13:35:05",
                "id": 149522,
                "league_name": "Sg. Premier League",
                "away_id": 2064,
                "score": "3 - 3",
                "competition_name": "Sg. Premier League",
                "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?key=demo_key&secret=demo_secret&id=149522",
                "home_id": 419,
                "away_name": "Balestier Khalsa FC",
                "added": "2019-07-19 11:30:05",
                "time": "FT",
                "home_name": "Warriors FC",
                "league_id": 130,
                "location": "Jurong East Stadium",
                "fixture_id": 1234500,
                "scheduled": "12:00"
            },
            {
                "competition_id": 370,
                "status": "FINISHED",
                "ht_score": "4 - 0",
                "ft_score": "6 - 1",
                "et_score": "",
                "last_changed": "2019-07-19 13:58:03",
                "id": 149523,
                "league_name": "Club Friendlies",
                "away_id": 549,
                "score": "6 - 1",
                "competition_name": "Club Friendlies",
                "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?key=demo_key&secret=demo_secret&id=149523",
                "home_id": 486,
                "away_name": "Swindon Town",
                "added": "2019-07-19 11:45:03",
                "time": "FT",
                "home_name": "Birmingham City",
                "league_id": 5,
                "location": "St Andrew's",
                "fixture_id": 1267356,
                "scheduled": "12:00"
            }
        ]
    }
}

Examples

cUrl

curl -XGET http://livescore-api.com/api-client/scores/live.json?key=demo_key\\&secret=demo_secret

PHP

file_get_contents('http://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret');

Python

import urllib2
req = urllib2.Request('http://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()

Getting live-scores by competition

To get the live-scores only for a certain competition, you have to provide the id of the competition as a get parameter in the api endpoint URL. In the example below, we show you how to get all the live-scores for Italy's Seria A. cUrl

curl -XGET http://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret\&competition_id=4

PHP

file_get_contents('http://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret&competition_id=4');

Python

import urllib2
req = urllib2.Request('http://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret&competition_id=4')
response = urllib2.urlopen(req)
print response.read()

Getting live-scores by country

To get the live-scores only for a certain country, you have to provide the id of the country as a get parameter in the api endpoint URL. In the example below, we show you how to get all the live-scores for all of Italy this includes Seria A, Seria B, Pro Lega, Cup and more. cUrl

curl -XGET http://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret\&country=47

PHP

file_get_contents('http://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret&country=47');

Python

import urllib2
req = urllib2.Request('http://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret&country=47')
response = urllib2.urlopen(req)
print response.read()