Standard Response Objects
On this page we list the standard nested objects structures that we use in our football API responses.
Competition
A competition is a standard object that reflects the tournament in which matches are happening. These competitions could be: domestic, international, leagues, cups, as well as club or national teams competitions. There are 2 "competitions" that are exception of these rules and they are the club friendlies (ID: 370) and the national teams friendlies (ID: 371)
{
"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
}
}Name Type Example Description tier number 1 The level of the competition in national competitions structure. For example, the English Premier League is tier 1 while the EFL Championship is tier 2. is_cup bool true Indicates where the competition is a cup true (e.g. The FA Cup, Coppa Italia, UEFA Champions League, FIFA World Cup, etc) or false when the competition is a league. (e.g. Serie A, The Bundesliga)is_league bool false The opposite of the is_cup field when the value of is_league is true then you are looking at a data piece of a league like the English Premier League. When the value is false you are looking at a cup like Svenska Cupen.has_groups bool true Indicates whether the competitions has groups with standings. Then the value of this field will be true, if the competition has only direct elimination matches the value will be false like in the case of the FA Cup. To get further details you can use our competitions groups API endpoint and the competition standings API endpointid number 244 The unique identifier of the competition in our database. It can be used as a filter in various football API endpoints like the live scores API, fixtures API, and matches history API. You can get the id of your desired competition using our competitions listing API endpoint or do a search on our competition coverage page. active bool true Indicates whether the competition is still active. Then the value is true. It could be false in the cases where the competition is not active any longer like the FIFA Confederations Cup (ID: 270)name string Ligue 1 The name of the competition national_teams_only bool true Indicates if the competition participants are only countries nations teams like Copa America ( true) or club competition (false) like La Liga.
Country
A country is a standard object that reflects the country in which matches are happening. This object will be available for all types of data that are on national level. While for the international level the federation standard object will be used. In such cases, the country value will be null.
{
"country": {
"is_real": true,
"id": 78,
"uefa_code": "GRE",
"name": "Greece",
"fifa_code": "GRE",
"flag": "GRE.png"
}
}Name Type Example Description id number 78 The unique identifier of the country in our database. It can be used as a filter in various football API endpoints like the live scores API, fixtures API, matches history API, teams listing API, competitions listing API and many more. name string England The name of the country is_real bool true Indicates whether this is a real country (value is true) or a legacy country (value is false). This is leftover from the time when the international football federations like FIFA, UEFA, and AFC were not a separate entity but handled as non-real country.uefa_code string ESP The 3 letter code that can identify the country with their UEFA membership. This abbreviation is regularly used in direct television broadcasts and online football match streams to indicate the national team of a country in the score bar. Only countries members of UEFA have values for this key, the rest of the countries will have an empty string as a value. fifa_code string ESP The 3 letter code that can identify the country with their FIFA membership. This abbreviation is also regularly used in direct television broadcasts and online football match streams to indicate the national team of a country in the score bar. All countries members of FIFA have values for this key, the rest of the countries will have an empty string as a value.
The edition is the connection link between a competition and a season. While a competition is a tournament like the English Premier League, the season is a worldwide time period in which competitions are held, the edition is a specific annual cycle of that competition. For example, the FIFA World Cup (Competition ID: 362) has different editions for the 2022 and 2018 seasons. Editions, allow us to separate data between different cycles of the same competition like the top goalscorers.
Edition
{
"edition": {
"id": 683,
"season_id": 11,
"is_current": true
}
}Name Type Example Description id number 683 The id of the editionseason_id number 11 The id of the season during which the edition of the competition is held. The id of season is different than the name of the season. To find out more about this, check our seasons football API endpointis_current bool true Indicates whether this is the currently held edition of the competition or it is a an old/historical edition
Federation
A federation is a standard object that reflects the international football association in which matches are happening. These are FIFA, UEFA, AFC, CAF, OFC, CONMEBOL, CONCACAF, IOC.
{
"federation": {
"id": 4,
"name": "AFC"
}
}Name Type Example Description id number 1 The unique identifier of the federation in our database. It can be used as a filter in various football API endpoints like the teams listing API, competitions listing API and many more. name string FIFA The name of the federation
Odds
The odds object contains two nested objects live and pre. They respectively contain 3 elements each "1", "X", and "2" which indicate the betting odds for home team win (1), draw (X), and away team win (2). The pre key contains the odds before the match started and they do not change. The live object contains the live match odds and they change as the match progresses.
The live odds are only available for certain packages. You can get more information on this support on our pricing page. These odds are averaged across many bookmakers to narrow down the full time odds from all of them to a single number.
{
"odds": {
"live": {
"1": 9,
"2": 1.36,
"X": 4.33
},
"pre": {
"1": 3.8,
"2": 1.8,
"X": 3.4
}
}
}Name Type Example Description live.1 number 1.90 The average odd for a home team win at the end of regular time (90 minutes). The number changes as the match progresses. live.X number 2.90 The average odd for a draw at the end of regular time (90 minutes). The number changes as the match progresses. live.2 number 3.90 The average odd for an away team win at the end of regular time (90 minutes). The number changes as the match progresses. pre.1 number 1.90 The average odd for a home team win at the end of regular time (90 minutes). The odds do not change once the match starts. pre.X number 2.90 The average odd for a draw at the end of regular time (90 minutes). The odds do not change once the match starts. pre.2 number 3.90 The average odd for an away team win at the end of regular time (90 minutes). The odds do not change once the match starts.
Outcomes
The outcomes object contains the betting result of the different parts of the match. These include the end of the first half, full time (90 minutes), the end of the extra time (120 minutes), and finally at the end of the penalty shootout. Each of the four sections outcomes may contain 4 values:
* 1 - the home team leads at the end of the period
* X - the score is a draw at the end of the period
* 2 - the away team leads at the end of the period
* null - the period has not yet ended or not applicable of this match
{
"outcomes": {
"half_time": "X",
"full_time": "1",
"extra_time": null,
"penalty_shootout": null
}
}Name Type Example Description half_time char X The betting outcome at the end of the 1st half (45 minutes) or null if the first half has not ended yetfull_time char X The betting outcome at the end of the 2nd half (90 minutes) or null if the second half has not ended yetextra_time char X The betting outcome at the end of the 2nd half of the extra time (120 minutes) or null if the first half has not ended yet or never happenedpenalty_shootout char 1 The betting outcome at the end of the penalty shootout or null if the shootout has not ended yet or never happened. This value cannot have a value of X since the purpose of the penalty shootout in a football match is to have a decisive winner.
Player
The player object contains general information about a football palyer.
{
"player": {
"id": 9559,
"name": "Cristiano Ronaldo"
}
}Name Type Example Description id number 9559 The unique identification of the player in our database name string Cristiano Ronaldo The name of the player
Scores
The scores object contains 5 keys that hold the scores which the match had at the end of the different match periods. This object works closely with the outcomes as the outcomes depend on the scores.
{
"scores": {
"score": "1 - 0",
"ht_score": "0 - 0",
"ft_score": "1 - 0",
"et_score": "",
"ps_score": ""
}
}Name Type Example Description score string 1 - 0 Contains the current match score or the end match score. Except for the penalty shootout. Before the match starts this field will have the value of ? - ?. If the match has a status of IN PLAY the score will reflect the current score. If the match is in HALF TIME BREAK or FINISHED the score will contain the score at the end of the first half (45 minutes) or the score at the end of regular time (90 minutes) respectively. If the match has finished after extra time (e.g. match time has the value AET) then the score will hold the score at the end of the 120 minutes of play. The penalty shootout score does not get reflected ever.ht_score string 2 - 1 The score of the match at the end of the 45 minutes, if reached. ft_score string 2 - 3 The score of the match at the end of the 90 minutes, if reached. et_score string 3 - 3 The score of the match at the end of the 120 minutes, if applicable. ps_score string 4 - 1 The score from the penalty shootout only. This means only the goals score during the shootout. The goals scored in the play time including the extra time do not get summed up in this field.
Season
Seasons are time periods spanning from 1 to 2 years. During these periods competition editions are being held. There are 2 types of seasons: a full year like 2023 and a cross year like 2023/2024. To find more about the seasons check our seasons football API endpoint.
{
"season": {
"id": 11,
"name": "2022",
"start": "2022-01-01",
"end": "2022-12-31"
}
}Column1 Column2 Column3 Column4 id number 11 The id of the season name string 2024 The name of the season start string 2024-01-01 The start date of the season end string 2024-12-31 The end date of the season
Team
The team object contains data about a football team. Whether in the teams listing API or in various football API match related endpoints like the live scores API, fixtures API, matches history API.
{
"team": {
"stadium": "Estadio F\u00e9lix Capriles",
"id": 279,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/a9ac0075f7236648796cf757658e4e06.png",
"name": "Jorge Wilstermann",
"country_id": "60"
}
}Name Type Example Description id number 279 The unique identification of the team in our database, it can used to cross reference the same team in various football API endpoints response data as well as filters in some API endpoints like the live scores API. name string Jorge Wilstermann The name of the football team either in English or the requested language if the package that you chose from our pricing page supports teams names translations country_id number 60 The unique identifier of the country from where the team is stadium string The Wembley Stadium The name of the stadium where usually the team plays their home games logo url A link to our CDN from where you can get the team logo. Getting the team logos does not count as a request against your quota. We update the team logos once a month at the 1st of the month, so you can cache the images until the 1st of the next month.
Urls
The structure of the urls object depends on the football API endpoint that you are using. The goal of this object is to provide you with direct links to related data to the objet in question. This makes integrating our API easier as you do not need to remember, read, or update the URLs of the related data as we will just update the URLs. The specific structure of the urls will be explained in the dedicated API endpoint documentation page. In order, to make use of the URLs all you have to do is append the key and secret parameters to the URL and call it.
For example, in the live scores API you get the head2head API endpoint link like this one: {"head2head": "https://livescore-api.com/api-client/teams/head2head.json?team1_id=5746&team2_id=204}" In this case the final usable link would something like this: https://livescore-api.com/api-client/teams/head2head.json?team1_id=5746&team2_id=204&key=your-api-key&secret=your-api-secret.