Getting live-scores

On this reference page, we explain how you can obtain the score of the matches that are currently played around the world.

This football 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, you use our history endpoint.

This football api endpoint supports teams names in various languages. To find out more about this, go to our documentation on language support.

NOTE: In our football API endpoints there are 2 ids for each football match. First, it is the fixture id, it is solely for the purpose of keeping track of scheduled matches. The fixture id is different than the match id, which is the second ID that we use. Every match gets an ID when it is about to start. 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


You have several options for filtering the live scores when using this football API endpoint. 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 has finished, it will stay in the live-score feed for up to 3 hours more. For example, if the game has ended after the regular time of 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 ended.


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 country, competition, competitions, or team. There is also a parameter that allow you to translate some of the data in different languages.


NameTypeRequiredExampleDescription
competition_idstring16Filters the scores user their competition_id. Or multiple competitions separated with commas.
countrynumber2Filters the matches by country in which they are played, or the general competition in case of Champions league.
langstringar2 letter ISO 639-1 language code.
team_idnumber19The id of a team, if we want only that teams live scores.

REPONSE


The response contains the following information for every match element in the list. The response data and its types is the same both for the JSON and XML data responses.


NameTypeExampleDescription
addeddatetime2018-03-23 14:27:02The date and time of when the match was added to our live-score api feed.
away_idinteger12as 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
away_namestringMan CityThe name of the away team.
competition_idnumber16The id of the competition in which the match takes places
competition_namestringSeria AThe name of the football competition in which the match takes places
et_scorestring2 - 0The extra time score of the game, if the extra time has been reached.
eventsstring,booleanhttp://....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.
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
ft_scorestring2 - 0The full time score of the game, if the full time has been reached.
h2hstring,booleanhttp://....The API endpoint that can be used to compare the 2 teams head 2 head
has_lineupsbooleantrueWhether we have the team lineups for this match
home_idinteger19as 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
home_namestringMan UnitedThe name of the home team.
ht_scorestring2 - 0The half time score of the game, if the half time has been reached.
idnumber49The id of the match, this is not the fixture id
last_changeddatetime2018-03-23 14:27:02The date and time of the last match data update.
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
odds.live.1number2.19The odds of the home team winning as the match is being played
odds.live.2number2.55The odds of the away team winning as the match is being played
odds.live.Xnumber4.13The odds of a draw as the match is being played
odds.pre.1number2.20The odds of the home team winning before the start of the match
odds.pre.2number2.50The odds of the away team winning before the start of the match
odds.pre.Xnumber4.00The odds of a draw before the start of the match
outcomes.extra_timestring2The outcome of match after the 2 halves of extra time have finished (120 minutes) 1, X, or 2
outcomes.full_timestringXThe outcome of the of the match after the 90 minutes: 1, X, or 2
outcomes.half_timestring1The outcome of the first half of the match 1, X, or 2
ps_scorestring4 - 5The score after the penalty shootout
scheduledstring12:00The hour and minute for which the match was schedule to start
scorestring2 - 0contains 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.
statusstringNOT STARTEDthe 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.
timeinteger67The number minutes that have passed since the kick-off.

{
    "success": true,
    "data": {
        "match": [
            {
                "scheduled": "13:00",
                "competition_id": 165,
                "ps_score": "",
                "location": "Stadioni Tamaz Stepania",
                "odds": {
                    "live": {
                        "X": 3.3,
                        "1": 1.65,
                        "2": 5
                    },
                    "pre": {
                        "X": null,
                        "1": null,
                        "2": null
                    }
                },
                "last_changed": "2021-06-08 14:53:02",
                "competition_name": "Erovnuli Liga 2",
                "home_id": 1399,
                "score": "2 - 2",
                "id": 257578,
                "away_name": "FC Merani Martvili",
                "time": "90+",
                "away_id": 5996,
                "ht_score": "1 - 1",
                "home_name": "Sioni Bolnisi",
                "added": "2021-06-08 13:03:02",
                "h2h": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?key=demo_key&team2_id=5996&secret=demo_secret&team1_id=1399",
                "status": "ADDED TIME",
                "has_lineups": false,
                "ft_score": "",
                "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?key=demo_key&secret=demo_secret&id=257578",
                "fixture_id": 1433692,
                "et_score": "",
                "outcomes": {
                    "half_time": "X",
                    "full_time": null,
                    "extra_time": null
                },
                "info": "This match is only supported through the new competitions structure"
            },
            {
                "scheduled": "13:00",
                "competition_id": 165,
                "ps_score": "",
                "location": "",
                "odds": {
                    "live": {
                        "X": 4,
                        "1": 1.65,
                        "2": 2.1
                    },
                    "pre": {
                        "X": null,
                        "1": null,
                        "2": null
                    }
                },
                "last_changed": "2021-06-08 14:53:02",
                "competition_name": "Erovnuli Liga 2",
                "home_id": 4844,
                "score": "3 - 2",
                "id": 257579,
                "away_name": "FC Wit Georgia",
                "time": "FT",
                "away_id": 4157,
                "ht_score": "1 - 1",
                "home_name": "Gareji",
                "added": "2021-06-08 13:03:03",
                "h2h": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?key=demo_key&team2_id=4157&secret=demo_secret&team1_id=4844",
                "status": "FINISHED",
                "has_lineups": false,
                "ft_score": "3 - 2",
                "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?key=demo_key&secret=demo_secret&id=257579",
                "fixture_id": 1433693,
                "et_score": "",
                "outcomes": {
                    "half_time": "X",
                    "full_time": "1",
                    "extra_time": null
                },
                "info": "This match is only supported through the new competitions structure"
            }
        ]
    }
}


EXAMPLES


cUrl:

curl -XGET "https://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret"
PHP:
file_get_contents('https://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret');
Python:
import urllib2
req = urllib2.Request('https://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 "https://livescore-api.com/api-client/scores/live.json?key=demo_key&secret=demo_secret&competition_id=4"
PHP:
file_get_contents('https://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret\&competition_id=4');
Python:
import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/scores/live.json?key=demo_key\&secret=demo_secret\&competition_id=4')
response = urllib2.urlopen(req)
print response.read()