Standings
Retrieve a league's standings or a team's ranking using Api-Football.
We'll cover the following
Standings show how teams rank in leagues and cups. If the team you want to see the standings for participates in numerous tournaments, it's time-consuming to read through the standings of each tournament to see how the team is doing. Api-Football not only gives tournament standings but can also tell us how a team is ranked across multiple tournaments with a single API call.
Get league standings
The Standings endpoint returns the standings for a league or the position of a team in multiple league/cup tables. The base URI for this endpoint is https://v3.football.api-sports.io/standings
.
Request parameters
The query parameters for this endpoint are as follows:
Parameters | Type | Category | Description |
| Integer | Optional | This is the ID of the league whose standings we want to see. We can get the ID of the league using the Leagues endpoint. |
| Integer | Required | This is the year for which we require the standings. |
| Integer | Optional | This is the ID of the team we want the stats for. We can use the Teams information endpoint to get this ID. |
Note: The
team
orleague
parameters must be used with theseason
parameter for this endpoint.
The Standings endpoint used with the league
and the season
parameters provides us with the standings in a league for the mentioned season. The code below uses these parameters with the endpoint. Click the “Run” button to see the response.
const date = new Date();const endpointUrl = new URL('https://v3.football.api-sports.io/standings');const queryParameters = new URLSearchParams({league:'39', // 39 is the league id for England's Premier Leagueseason: date.getFullYear()});headerParameters = {'x-rapidapi-host': 'v3.football.api-sports.io','x-rapidapi-key': '{{API_KEY}}'}const options = {method: 'GET',headers: headerParameters};async function fetchLeagueStandings() {try {endpointUrl.search = queryParameters;const response = await fetch(endpointUrl, options);printResponse(response);}catch (error) {printError(error);}}fetchLeagueStandings();
Here is the code explanation:
Line 2: We set the URL to
https://v3.football.api-sports.io/standings
.Lines 4–12: We define the query parameters and header parameters. We can change the league ID, and the year we want the standings for in line 5 and line 6, respectively, to get the standings of another league.
Lines 14–17: We set the request type and appropriate header.
Lines 19–28: We define a function,
fetchLeagueStandings()
. It calls the endpoint and prints the response.
Note: We can use the Leagues endpoint to get the league ID as described in the Support Endpoints lesson in the Appendix.
The Standings endpoint used with the season
and team
parameters returns the standings of the team in its respective league. Click the “Run” button to call the Standings endpoint with these parameters.
const date = new Date();const endpointUrl = new URL('https://v3.football.api-sports.io/standings');const queryParameters = new URLSearchParams({team:'33', // 33 is the team id for Manchester Unitedseason: date.getFullYear()});headerParameters = {'x-rapidapi-host': 'v3.football.api-sports.io','x-rapidapi-key': '{{API_KEY}}'}const options = {method: 'GET',headers: headerParameters};async function fetchTeamStandings() {try {endpointUrl.search = queryParameters;const response = await fetch(endpointUrl, options);printResponse(response);}catch (error) {printError(error);}}fetchTeamStandings();
Let's look at the changes we've made in the code:
Lines 4–7: We change the query parameters. We can get standings for other teams by changing the team ID in line 5.
Line 19: We change the function's name to
fetchTeamStandings()
.
Response fields
The table below contains some important response fields of this endpoint:
Response Fields | Type | Description |
| Object | This object contains information about the league whose standings are retrieved by the API. |
| Object [array] | This array is inside the |
Note: The details about the elements in these objects are discussed in the Response Elements lesson in the Appendix.