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.

Press + to interact

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

league

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.

season

Integer

Required

This is the year for which we require the standings.

team

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 or league parameters must be used with the season 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.

Press + to interact
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 League
  season: 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.

Press + to interact
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 United
  season: 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

league

Object

This object contains information about the league whose standings are retrieved by the API.

standings

Object [array]

This array is inside the league object. It contains information about the league standings.

Note: The details about the elements in these objects are discussed in the Response Elements lesson in the Appendix.