Live scores

  1. Endpoint
  2. Parameters
  3. Reponse
  4. Examples
  5. Getting Live-scores By Competition

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 should use our history endpoint. If you want to get matches that are scheduled, you should use our fixtures API endpoint.

This football api endpoint supports data in various languages. To find out more about this, check out our documentation on language support.

ENDPOINT


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, usually 15 minutes before kickoff. 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.


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.


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_idstring67,27Filters the live matches by the listed competitions ids separated by a comma
competition_idnumber16Filters the scores user their competition
country_idnumber2Filters the matches by country in which they are played.
fixture_idnumber1580503The id of the fixture from our fixtures calendar API endpoint, if you want to get the live match for that specific fixture.
langstringar2 letter ISO 639-1 language code. Find out more on our data in various languages.
team_idnumber19The id of a team, if we want only that teams live scores.

REPONSE


NameTypeExampleDescription
addedstring2023-12-18 07:45:06The date and time of when the match was added to our live-score api feed.
awayobject{}An object holding the information about the away team in the match. It has the structure of our standard team object.
competitionobject{}An object holding the information about the competition in which the match is being played. It has the structure of our standard competition object.
countryobject{}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.
federationobject{}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_idnumber1657338The 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
homeobject{}An object holding the information about the home team in the match. It has the structure of our standard team object.
idnumber483252The id of the match, this is not the fixture id
last_changeddatetime2023-12-18 08:42:53The 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.
locationstringCampbelltown StadiumThe place where the match takes place, it can be the stadium name, the city name, both, or it can even include the country name
oddsobject{}An object that holds information about the pre match and live match betting odds. It has the structure of a standard odds object
outcomesobject{}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
scheduledstring08:00The hour and minute for which the match was schedule to start in UTC
scoresobject{}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
statusstringIN PLAYthe 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 football 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.
timestring43The number minutes that have passed since the kick-off. When the match is in status HALF TIME BREAK the value of the time will be HT. When the match is in the FINISHED status the value of time can be one of the 3 following options:
FT - Means that the 90 minutes have finished
AET - Means that the 120 minutes have finished
AP - Means that the penalty shootout has finished.
urlsobject{}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 endpoint
lineups - 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.

{
    "success": true,
    "data": {
        "match": [
            {
                "country": {
                    "is_real": true,
                    "id": 71,
                    "uefa_code": "",
                    "name": "Australia",
                    "fifa_code": "AUS",
                    "flag": "AUS.png"
                },
                "last_changed": "2023-12-18 08:42:53",
                "home": {
                    "stadium": "Campbelltown Stadium",
                    "id": 6581,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/b9d463b08c43de617618f7ec65a54cc3.png",
                    "name": "Macarthur",
                    "country_id": "71"
                },
                "added": "2023-12-18 07:45:06",
                "status": "IN PLAY",
                "federation": null,
                "location": "Campbelltown Stadium",
                "scheduled": "08:00",
                "competition": {
                    "tier": 1,
                    "is_cup": false,
                    "has_groups": true,
                    "id": 67,
                    "active": true,
                    "name": "Hyundai A-League",
                    "is_league": true,
                    "national_teams_only": false
                },
                "id": 483252,
                "time": "43",
                "fixture_id": 1657338,
                "odds": {
                    "live": {
                        "1": 5.6,
                        "2": 1.61,
                        "X": 3.55
                    },
                    "pre": {
                        "1": 2,
                        "2": 3.45,
                        "X": 3.85
                    }
                },
                "away": {
                    "stadium": "Westpac Stadium",
                    "id": 202,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/004d52954bd4936cc14e30b4511073ab.png",
                    "name": "Wellington Phoenix",
                    "country_id": "71"
                },
                "outcomes": {
                    "half_time": null,
                    "full_time": null,
                    "extra_time": null,
                    "penalty_shootout": null
                },
                "scores": {
                    "score": "0 - 1",
                    "ht_score": "",
                    "ft_score": "",
                    "et_score": "",
                    "ps_score": ""
                },
                "urls": {
                    "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?id=483252",
                    "statistics": "https:\/\/livescore-api.com\/api-client\/matches\/stats.json?match_id=483252",
                    "lineups": "https:\/\/livescore-api.com\/api-client\/matches\/lineups.json?match_id=483252",
                    "head2head": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?team1_id=6581&team2_id=202"
                }
            },
            {
                "country": {
                    "is_real": true,
                    "id": 90,
                    "uefa_code": "",
                    "name": "Indonesia",
                    "fifa_code": "IDN",
                    "flag": "IDN.png"
                },
                "last_changed": "2023-12-18 08:42:52",
                "home": {
                    "stadium": "Stadion Brawijaya",
                    "id": 5746,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/ee2fd3a662dc351faf3b6fa4e1b57074.png",
                    "name": "Persik Kediri",
                    "country_id": "90"
                },
                "added": "2023-12-18 07:45:07",
                "status": "IN PLAY",
                "federation": null,
                "location": "Stadion Brawijaya",
                "scheduled": "08:00",
                "competition": {
                    "tier": 1,
                    "is_cup": false,
                    "has_groups": true,
                    "id": 27,
                    "active": true,
                    "name": "GO-JEK Liga 1",
                    "is_league": true,
                    "national_teams_only": false
                },
                "id": 483253,
                "time": "43",
                "fixture_id": 1624810,
                "odds": {
                    "live": {
                        "1": 2.38,
                        "2": 3.6,
                        "X": 2.43
                    },
                    "pre": {
                        "1": 1.98,
                        "2": 3.3,
                        "X": 3.15
                    }
                },
                "away": {
                    "stadium": "Stadion Andi Mattalatta",
                    "id": 204,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/d39724be7ff1da90678b25cf3be6e6f1.png",
                    "name": "PSM Makassar",
                    "country_id": "90"
                },
                "outcomes": {
                    "half_time": null,
                    "full_time": null,
                    "extra_time": null,
                    "penalty_shootout": null
                },
                "scores": {
                    "score": "0 - 0",
                    "ht_score": "",
                    "ft_score": "",
                    "et_score": "",
                    "ps_score": ""
                },
                "urls": {
                    "events": "https:\/\/livescore-api.com\/api-client\/scores\/events.json?id=483253",
                    "statistics": "https:\/\/livescore-api.com\/api-client\/matches\/stats.json?match_id=483253",
                    "lineups": "https:\/\/livescore-api.com\/api-client\/matches\/lineups.json?match_id=483253",
                    "head2head": "https:\/\/livescore-api.com\/api-client\/teams\/head2head.json?team1_id=5746&team2_id=204"
                }
            }
        ]
    }
}


EXAMPLES


cUrl:

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


Didn't find what you need?

Do no hesitate to contact us. We will get back to you as soon as possible.