This reference explains how to retrieve live football scores through the football API. It covers the endpoint, request parameters, and response format so you can integrate real-time match data into your application.
ENDPOINT
In our football API endpoints, each football match uses two separate IDs. The fixture ID tracks scheduled matches only. The match ID is different and is assigned to every match when it is about to start, usually 15 minutes before kickoff. After the match ends and moves into the history database, the match ID persists and stays the same. The fixture ID and match ID for the same match are completely different. That is why the fixture_id field appears in both the live score API endpoint and the history API endpoint.
When working with this football API endpoint, live score filtering can be handled in more than one way. Fetching the complete match list is covered in the opening section of this page. Narrowing results down to a single competition or a single country requires passing the corresponding competition ID or country ID. Both approaches are detailed in the second and third parts of this reference.
Fetching live scores for matches currently in play requires nothing more than a call to the URL below. After a game ends, it remains in the live score feed for up to 3 additional hours. For instance, a match that finishes after the regular 90 minutes stays available in the feed with a FINISHED status for another hour and 15 minutes. When extra time is played, the game stays available for 45 minutes after the extra time concludes.
Check this Football API endpoint in our postman collection. Download it now!
PARAMETERS
The live scores API endpoint accepts multiple parameters for narrowing down matches by country, competition, competitions, or team. An additional parameter lets you translate parts of the returned data into different languages.
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| competition_id | string | 67,27 | Narrow the live match results using the specified competition ids, which must be supplied as a comma separated list. | |
| competition_id | number | 16 | Refine the returned scores according to the competition supplied by the caller. | |
| country_id | number | 2 | Narrows the returned matches down to those played in a specific country. | |
| fixture_id | number | 1580503 | The football API fixture identifier retrieved from our fixtures calendar endpoint. Supply this fixture id when your integration needs to pull live match data for one specific fixture. | |
| lang | string | ar | A two letter ISO 639-1 language code. Learn more about our football data in various languages. | |
| team_id | number | 19 | The team ID, used when you want live scores for that team only. |
REPONSE
| Name | Type | Example | Description |
|---|---|---|---|
| added | string | 2023-12-18 07:45:06 | A timestamp indicating the moment the match first entered our live score football API feed. |
| away | object | {} | Carries details about the away side in the match. Its layout follows our standard team object. |
| competition | object | {} | Carries details about the competition hosting the match. Its layout follows our standard competition object. |
| country | object | {} | Carries details about the nation where the match takes place. Its layout follows our standard country object. When the match belongs to an international competition such as the UEFA Champions League, the country field resolves to null. |
| federation | object | {} | Carries details about the federation overseeing the match. Its layout follows our standard federation object. When the match belongs to a national competition such as the English Premier League, the federation field resolves to null. |
| fixture_id | number | 1657338 | The fixture id tied to this match. This value may come back as 0 or null, which signals that no fixture was registered before the match kicked off. |
| home | object | {} | Carries details about the home side in the match. Its layout follows our standard team object. |
| id | number | 483252 | The match id, which is distinct from the fixture id. |
| last_changed | datetime | 2023-12-18 08:42:53 | A UTC timestamp marking the most recent update to the match data. While play is underway this value refreshes frequently. Once the match reaches FINISHED or HALF TIME BREAK status, updates become far less frequent since no active play is occurring. |
| location | string | Campbelltown Stadium | The venue for the match. This field may contain the stadium name, the city name, both combined, or even the country name depending on the data available. |
| odds | object | {} | Carries pre match and in play betting odds. Its layout follows our standard odds object. |
| outcomes | object | {} | Carries betting outcome data (1, X, 2) across the various match periods. Its layout follows our standard outcomes object. |
| scheduled | string | 08:00 | The scheduled kick off time for the match, expressed in UTC as hour and minute. |
| scores | object | {} | Carries score line details recorded at the close of each match period. Its layout follows our standard scores object |
| status | string | IN PLAY | The current state of the match. |
| time | string | 43 | The elapsed minute count since kick off. While the match sits in HALF TIME BREAK status the time field returns HT. |
{
"success": true,
"data": {
"match": [
{
"time": "FT",
"federation": {
"id": 1,
"name": "FIFA"
},
"added": "2026-09-30 11:45:10",
"id": 735754,
"competition": {
"id": 371,
"is_cup": true,
"is_league": false,
"tier": 0,
"active": true,
"name": "National Teams Friendlies",
"national_teams_only": false,
"has_groups": false
},
"country": null,
"last_changed": "2026-09-30 14:53:30",
"away": {
"name": "Sri Lanka",
"logo": "https:\/\/cdn.football-api.com\/teams\/2708.png",
"id": 2708,
"country_id": 116,
"stadium": ""
},
"fixture_id": 1902314,
"home": {
"name": "Seychelles",
"logo": "https:\/\/cdn.football-api.com\/teams\/2766.png",
"id": 2766,
"country_id": 118,
"stadium": "Stade Linit\u00e9"
},
"scheduled": "13:00",
"location": "Stade Linit\u00e9",
"status": "FINISHED",
"odds": {
"live": {
"1": 1.0100000000000000088817841970012523233890533447265625,
"2": 1.060000000000000053290705182007513940334320068359375,
"X": 8.5
},
"pre": {
"1": 4.0999999999999996447286321199499070644378662109375,
"2": 1.7800000000000000266453525910037569701671600341796875,
"X": 3.20000000000000017763568394002504646778106689453125
}
},
"outcomes": {
"half_time": "2",
"full_time": "2",
"extra_time": null,
"penalty_shootout": null
},
"scores": {
"score": "0 - 2",
"ht_score": "0 - 1",
"ft_score": "0 - 2",
"et_score": "",
"ps_score": ""
}
},
{
"time": "24",
"federation": {
"id": 1,
"name": "FIFA"
},
"added": "2026-09-30 11:45:22",
"id": 735755,
"competition": {
"id": 371,
"is_cup": true,
"is_league": false,
"tier": 0,
"active": true,
"name": "National Teams Friendlies",
"national_teams_only": false,
"has_groups": false
},
"country": null,
"last_changed": "2026-09-30 12:23:41",
"away": {
"name": "Djibouti",
"logo": "https:\/\/cdn.football-api.com\/teams\/4992.png",
"id": 4992,
"country_id": 118,
"stadium": "Stade El Hadj Hassan Gouled"
},
"fixture_id": 1900823,
"home": {
"name": "Mauritius",
"logo": "https:\/\/cdn.football-api.com\/teams\/4368.png",
"id": 4368,
"country_id": 118,
"stadium": "New George V Stadium"
},
"scheduled": "12:00",
"location": "New George V Stadium",
"status": "IN PLAY",
"odds": {
"live": {
"1": null,
"2": null,
"X": null
},
"pre": {
"1": null,
"2": null,
"X": null
}
},
"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": ""
}
},
{
"time": "78",
"federation": {
"id": 1,
"name": "FIFA"
},
"added": "2026-09-30 13:45:23",
"id": 735758,
"competition": {
"id": 371,
"is_cup": true,
"is_league": false,
"tier": 0,
"active": true,
"name": "National Teams Friendlies",
"national_teams_only": false,
"has_groups": false
},
"country": null,
"last_changed": "2026-09-30 15:30:28",
"away": {
"name": "Mozambique",
"logo": "https:\/\/cdn.football-api.com\/teams\/2771.png",
"id": 2771,
"country_id": 118,
"stadium": "Est\u00e1dio Nacional do Zimpeto"
},
"fixture_id": 1902075,
"home": {
"name": "Botswana",
"logo": "https:\/\/cdn.football-api.com\/teams\/2754.png",
"id": 2754,
"country_id": 118,
"stadium": "Botswana National Stadium"
},
"scheduled": "14:00",
"location": "Botswana National Stadium",
"status": "IN PLAY",
"odds": {
"live": {
"1": null,
"2": null,
"X": null
},
"pre": {
"1": null,
"2": null,
"X": null
}
},
"outcomes": {
"half_time": "X",
"full_time": null,
"extra_time": null,
"penalty_shootout": null
},
"scores": {
"score": "0 - 1",
"ht_score": "0 - 0",
"ft_score": "",
"et_score": "",
"ps_score": ""
}
}
]
}
}Match Statuses
The live match status values your integration may receive are:
| Status | Meaning |
|---|---|
NOT STARTED | The match has yet to begin, though kick off is imminent. |
IN PLAY | The match is currently underway. |
HALF TIME BREAK | The half time interval is in progress. |
ADDED TIME | The match is in stoppage time during either the first or second half. Do not mistake this for extra time, which is used when a winner cannot be determined after regulation. |
FINISHED | The match has completed its regulation two halves. |
INSUFFICIENT DATA | The game is in progress, but due to underlying issues we cannot supply reliable data. |
Match Time
Once the match reaches FINISHED status the time value resolves to one of three outcomes:
| Time | Meaning |
|---|---|
FT | The regulation 90 minutes have concluded |
AET | The full 120 minutes have concluded |
AP | The penalty shootout has concluded. |
EXAMPLES
cUrl:
curl -XGET "https://api.football-api.com/matches/live.json?key=demo_key&secret=demo_secret"file_get_contents('https://api.football-api.com/matches/live.json?key=demo_key\&secret=demo_secret');import urllib2
req = urllib2.Request('https://api.football-api.com/matches/live.json?key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()GETTING LIVE-SCORES BY COMPETITION
To pull live scores for one specific competition, pass the competition id as a GET parameter inside the football API endpoint URL. The sample below demonstrates how to retrieve every live score for Italy's Serie A.
cUrl:
curl -XGET "https://api.football-api.com/matches/live.json?key=demo_key&secret=demo_secret&competition_id=4"file_get_contents('https://api.football-api.com/matches/live.json?key=demo_key\&secret=demo_secret\&competition_id=4');import urllib2
req = urllib2.Request('https://api.football-api.com/matches/live.json?key=demo_key\&secret=demo_secret\&competition_id=4')
response = urllib2.urlopen(req)
print response.read()