Teams Statistics

Learn and practice how to fetch statistics related to football teams.

We'll cover the following

Statistics of a team provide us insight into the core of the team. It can help us analyze the performance of a team using factual data.

Get stats of a team

The Teams statistics endpoint provides the statistics of a team. The statistics are shown for the competition and season mentioned in the query parameters. The API returns the statistics of all the games played by the team for the said competition and season. The base URI for this endpoint is https://v3.football.api-sports.io/teams/statistics.

Request parameters

The query parameters for this endpoint are as follows:

Parameters

Type

Category

Description

league

Integer

Required

This is the ID of the league we want to search for.

season

Integer

Required

This is the season we want to search for. The format is "YYYY."

team

Integer

Required

This is the ID of the team whose stats we want to see. This ID can be retrieved using the Teams information endpoint.

date

String

Optional

This is the date limit. We'll see the statistics of the team to this date. Its format is "YYYY-MM-DD."

Requesting for the Teams statistics endpoint without the date parameter gives the statistics for the whole season. The widget below contains the code where this endpoint is being called without the date parameter. Click the “Run” button to execute the GET request and see the JSON response.

Press + to interact
const date = new Date();
const endpointUrl = new URL('https://v3.football.api-sports.io/teams/statistics');
const queryParameters = new URLSearchParams({
  league: '39', // 39 is the league id for England's Premier League
  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 fetchStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchStats();

Following is a brief explanation of the code above:

  • Line 2: We set the URL to https://v3.football.api-sports.io/teams/statistics.

  • Lines 4–13: We define the query parameters and header parameters. We can get the statistics for the other teams by changing the league ID in line 5, the team ID in line 6, and the year we want the stats for in line 7.

  • Lines 15–18: We set the request type and appropriate header.

  • Lines 20–29: We define a function, fetchStatus(). It calls the endpoint and prints the response.

Note: We can obtain the league ID and the team ID using the Leagues endpoint, as explained in the Support Endpoints lesson in the Appendix, and Teams information endpoint, as explained in the previous Teams Information lesson.

Requesting the Teams statistics endpoint with the date parameter gives us similar kinds of statistics as above, but the data is confined to the supplied date rather than the entire season. Click the “Run” button below to see the output.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/teams/statistics');
const queryParameters = new URLSearchParams({
  league: '39', // 39 is the league id for England's Premier League
  team: '33', // 33 is the team id for Manchester United
  season: '2019',
  date: '2019-10-08'
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchLimitedStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchLimitedStats();

Let's look at how we've modified the code:

  • Lines 3–8: We change the query parameters. Just like in the first case, we can get the data for the other teams by changing the value of the query parameters in the code.

  • Line 20: We change the function's name to fetchLimitedStats().

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 the stats are fetched from.

team

Object

This object contains the ID, name, and link for the logo of the team to which the stats are related.

form

String

This string represents the outcome of the previous matches of the team.

fixtures

Object

This object contains information about the fixtures whose stats are returned.

goals

Object

This object contains detailed information about the number of goals scored and conceded by the team in the specified season.

biggest

Object

This object contains information about the longest win streak, biggest win margins, biggest loss margin, and the goals scored by the team in the specified season.

clean_sheet

Object

This object contains detailed information about the number of goals scored and conceded by the team in the specified season.

failed_to_score

Object

This object contains information about the number of times the team failed to score in the specified season.

penalty

Object

This object contains information about the penalties scored and missed by the team in the specified season.

lineups

Object

This object contains information about the formations used by the team in the specified season.

cards

Object

This object contains information about the yellow and red cards taken by the team's players in the specified season.

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