Events

Learn how to get critical events from a fixture.

We'll cover the following

In a football match, there are some events that shape the whole match, and some even decide the result. Using Api-Football, we can retrieve those fixture events.

Get fixtures’ highlights

The Events endpoint fetches the highlight events of a fixture. We can get the following events using this endpoint:

  • Goals
  • Cards
  • Substitutions
  • VAR

Note: VAR events are available starting from the 2020-2021 season.

The base URI of this endpoint is https://v3.football.api-sports.io/fixtures/events.

Request parameters

We can use the following query parameters with the Events endpoint:

Parameters

Type

Category

Description

fixture

Integer

Required

This is the ID of the fixture for which we want the events. We can get the ID of the fixture using the Fixtures endpoint.

team

Integer

Optional

This is the ID of the team whose highlight events we want to see.

player

Integer

Optional

This is the ID of the player we want the events in response to be related to. We can get this ID using the Players endpoint.

type

String

Optional

This is the type of statistic we want. These types have already been discussed in the first paragraph of the lesson.

We can send the fixture ID as the query parameter with this endpoint to get all the available events for a fixture. The code below calls the endpoint with this parameter. Click the “Run” button to initiate the GET request.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/events');
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 fetchFixtureEvents() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchFixtureEvents();

Following is the code explanation:

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

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

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

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

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

We can use the team and the type parameters to get a specific type of event for one of the teams participating in the fixture. The code to get this data is in the widget below. Click the “Run” button to make the API call and see the response.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/events');
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  
  type: 'card'       
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchFixtureEvents() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchFixtureEvents();

We’ve added the teams and type parameters in lines 6-7 to filter the result we got using the previous widget. We can get the same type of events for the other team by changing the team ID in line 6. To get a different type of event in response, we can change the event type in line 7.

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

Response fields

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

Response Fields

Type

Description

time

Object

This object contains information about the minutes in which the event took place.

team

Object

This object contains the ID, name, and logo of the team that the event is related to.

player

Object

This object contains the name and ID of the player to whom the event is related.

type

String

This tells us the type of event.

detail

String

This is the detailed information about the event.