Statistics

Learn how to get the statistics of a fixture.

We'll cover the following

The outcome of a game does not always reflect how the teams performed. It is not uncommon for the superior team to lose. We can examine the statistics of a game to determine which team dominated. Api-Football can assist us in retrieving those statistics.

Press + to interact

Fetch stats of fixtures

We use the Statistics endpoint to get the statistics of a fixture. The base URI for this endpoint is https://v3.football.api-sports.io/fixtures/statistics.

Request parameters

Following are the query parameters we can use with the Statistics endpoint:

Parameters

Type

Category

Description

fixture

Integer

Required

This is the ID of the fixture whose statistics are required.

team

Integer

Optional

This is the ID of the team whose statistics we want. We can get the ID of the team using the Teams information endpoint.

type

String

Optional

This is the type of statistic we want.

Note: To look at the list of valid statistics types for this endpoint, click here.UntitledConcept2

Sending just the fixture ID as the query parameter with the Statistics endpoint provides us with all the fixture statistics. Click the “Run” button to get the stats for a fixture.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/statistics');
const queryParameters = new URLSearchParams({
  fixture: '215662' // 215662 is the fixture ID for the match between 
                    // Aldosivi and Defensa Y Justicia, which took place on 2019-10-20
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchFixtureStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchFixtureStats();

Following is the code explanation:

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

  • Lines 3–11: We define the query parameters and header parameters. We can change the fixture ID in line 4 to get information for another fixture.

  • Lines 13–16: We set the request type and appropriate header.

  • Lines 18–27: We define a function, fetchFixtureStats(). It calls the endpoint and prints the response.

Note: We can obtain the fixture ID by using the Fixtures endpoint, as we learned in the Fixtures Information lesson.

We can filter the statistics team-wise by using the team parameter. The code to get the filtered data is in the widget below. Click the “Run” button to get the statistics.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/statistics');
const queryParameters = new URLSearchParams({
  fixture: '215662', // 215662 is the fixture ID for the match between 
                     // Aldosivi and Defensa Y Justicia, which took place on 2019-10-20
  team: '463' // 463 is the team id for Aldosivi
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchFixtureStats() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchFixtureStats();

We've added the team query parameter in this code to filter the response we got from the previous widget. We can get the statistics for the other team by changing the team ID in line 6.

Note: We can get the team ID using the Teams endpoint, as explained in the Teams Information lesson.

By using the type parameter as in the widget below, we get a specific type of statistic in response. Click the “Run” button to get the statistics.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/statistics');
const queryParameters = new URLSearchParams({
  fixture: '215662', // 215662 is the fixture ID for the match between 
                    // Aldosivi and Defensa Y Justicia, which took place on 2019-10-20
  type: 'Total Shots'
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchSpecificStat() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchSpecificStat();

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

  • Line 6: We replace the team parameter with the type parameter. We can change the type of statistic in this line to get any other statistic for this fixture.
  • Line 19: We change the function’s name to fetchSpecificStat().

Response fields

The table below contains some important response fields of this endpoint:

Response Fields

Type

Description

team

Object

This object contains information about the team participating in the specified fixture to whom the stats are related to. It has the following elements:

  • id: This is the ID of the team.
  • name: This is the ID of the team.
  • logo: This is the link for an image of the team logo.

statistics

Object

This object contains statistics of the team from the specified fixture. It has the following elements:

  • type: This tells the type of the returned statistic.
  • value: This is the value of the statistic.