Competition Standings
On the football API reference page, we explain how our competition table API endpoint works.
Competition table standings are a vital part of the football data that people are interested in. It is no longer that only the live scores, fixtures, or history data matters. We provide our subscribers with the possibility to get the current standings of any competition using this dedicated football API endpoint. This API endpoint provides all the standings for all the groups in a given competition for a given season. If you want to get the standings for a specific group you should use the group standings API endpoint.
Seasons
Before you are able to get the data for a specific competition you have to know the ID of the season for which you want the standings. As we know, every season there is a new table with new and new standings in it. Below we have outlined the seasons that we have and what are their respective ids as well as some example competitions that might have standings for this season.
In our football API, there are 2 kinds of seasons. Whole calendar year season e.g. 2020 or an autumn/spring season e.g. 2018/2019. The season that a competition might have depends on the period during which it takes place. Let's take for example, the English Premier League (ID 2). Since it starts in the autumn and ends in the spring will use the second type of season (2021/2022). Competitions like the Swedish Allsvenskan (ID 14) and the Brazileiro (ID 24) which start at the beginning of the calendar year and are completed towards the end of the same year get the first type of season format (2022).
When it comes to qualifiers for international tournaments involving national teams the season for the qualification group standings is the same as the season in which the final tournament will take place. For example, the season for the UEFA EURO Qualifiers Groups is (2020)!
You can find more about our seasons and their IDs on the seasons list documentation page.
Endpoint
In order, to get the standings table for a football competition from our football API the only thing you need to do is the call the URL bellow. We are supporting table standings data for 400+ competitions from all over the globe.
The standings table football API endpoint supports several parameters that you can use to filter the football data and traverse through it at your convenience. The parameters are listed in the table below. You can use the parameters together as well as separately. This football API endpoint returns the standings for all groups for all stages for a given season. If you want to get the standings for a specific group you should use our dedicated group standings API endpoint.
For example, the English Premier League has one stage (Regular Season) and one group in it. The UEFA Euro has one group stage with multiple groups in it. The Bulgarian First Professional League has multiple stages (Regular season, promotional round, and relegation) with one group in each stage. Calling this football API endpoint will return all the standings for all the groups for the given season.
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| competition_id | Number | 1 | 2 | The ID of the competition which standings you need |
| include_form | integer | 1 | Includes the last 6 matches team form to the response data | |
| lang | String | ar | The ISO alpha2 code of the language in which you want the team names. | |
| season | Number | 11 | The ID of the season for which you need the standings. This parameter is useful if you want the standings for past seasons. If this parameter is not provided the football API endpoint will return the standings for the most current season of the competition. |
Response
A response to a request will contain all the teams in the table with standings with their relevant information. There is a JSON example below. We show a fraction of the teams participating in the English Premier League. An actual response will contain all 20 teams, it is just too big for us to put all of the data in this page.
{
"success": true,
"data": {
"competition": {
"id": 2,
"name": "Premier League",
"is_league": true,
"is_cup": false,
"tier": 1,
"has_groups": true,
"active": true,
"national_teams_only": false
},
"season": {
"id": 26,
"name": "2023\/2024",
"start": "2023-07-01",
"end": "2024-06-30"
},
"stages": [
{
"stage": {
"id": 2602,
"name": "Regular Season"
},
"groups": [
{
"id": 2684,
"name": "1",
"standings": [
{
"rank": 1,
"points": 51,
"matches": 22,
"goal_diff": 32,
"goals_scored": 51,
"goals_conceded": 19,
"lost": 1,
"drawn": 6,
"won": 15,
"team": {
"id": 7,
"name": "Liverpool",
"stadium": "Anfield",
"country_id": 19,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/a5734fc8b210472799a4f3e7006f8eee.png"
}
},
{
"rank": 2,
"points": 46,
"matches": 21,
"goal_diff": 27,
"goals_scored": 51,
"goals_conceded": 24,
"lost": 3,
"drawn": 4,
"won": 14,
"team": {
"id": 12,
"name": "Manchester City",
"stadium": "Etihad Stadium",
"country_id": 19,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/8415305916fb55e76fdd5ea4cf5b87ae.png"
}
},
{
"rank": 3,
"points": 46,
"matches": 22,
"goal_diff": 23,
"goals_scored": 44,
"goals_conceded": 21,
"lost": 4,
"drawn": 4,
"won": 14,
"team": {
"id": 18,
"name": "Arsenal",
"stadium": "Emirates Stadium",
"country_id": 19,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/1387bf948469b62b78f0f022dda33953.png"
}
}
]
}
]
}
]
}
}| Name | Type | Example | Description |
|---|---|---|---|
| competition | object | {} | An object holding the information about the competition for which you are getting the standings. It has the structure of our standard competition object. |
| drawn | Number | 7 | the number of drawn matches |
| form | Array | W, L, D | The for of the team in the last 6 matches from the competition |
| goal_diff | Number | 52 | the goal difference of the team, if it is negative, it will be a negative number e.g. -6 |
| goals_conceded | Number | 18 | the number of goals the team conceded in their own goal |
| goals_scored | Number | 70 | the number of goals the team scored in their opponents goals |
| lost | Number | 1 | the number of games the team lost |
| matches | Number | 31 | the number of matches that the team has played |
| points | Number | 76 | number of points accumulated |
| rank | Number | 1 | the rank in the standings table that the team occupies |
| season | object | {} | An object holding the information about the season for which you are getting the standings of the competition. It has the structure of our standard season object. |
| stages | array | [] | A list with all the stages that contain groups with standings with their respective data |
| stages.groups | array | [] | An array holding the information about the all the groups in a stage with their standings |
| stages.groups.standings.team | object | {} | An object holding the information about the team in the standings. It has the structure of our standard team object. |
| stages.stage | object | {} | An object holding information about the stage: id and name |
| won | Number | 23 | the number of matches the team won |
Examples
cUrl:
curl -XGET "https://livescore-api.com/api-client/competitions/table.json?competition_id=2&key=demo_key&secret=demo_secret"file_get_contents('https://livescore-api.com/api-client/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret');import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()In the examples bellow you can see how you can request the team form trough your request. To do that you need to add the following query parameter to your football API request. &include_form=1. Here are some examples:
cUrl:
curl -XGET "https://livescore-api.com/api-client/competitions/table.json?competition_id=2&key=demo_key&secret=demo_secret&include_form=1"file_get_contents('https://livescore-api.com/api-client/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret\&include_form=1');import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/table.json?competition_id=2\&key=demo_key\&secret=demo_secret\&include_form=1')
response = urllib2.urlopen(req)
print response.read()