Events

Events in a football match are crucial moments that define the course and outcome of the fixture. Each event type is represented by a unique code, allowing you to track and analyse various events during a match. Here's how you can use the events include to retrieve detailed information about specific events in a fixture. You can find all the event types below:

Events

How to use the include

To include events in your API requests, add the &include=events parameter. For a GET Fixture by ID request, the URL would look like this:

https://api.sportmonks.com/v3/football/fixtures/{fixture_ID}&include=events

Fields

The "id" field in the events response serves as a unique identifier for each event. The "fixture_id" corresponds to the associated fixture, while the "team_id" identifies the team related to the event. The "player_id" field represents the player associated with the event, and "related_event_id" links related events (e.g., a goal and an assist). The "minute" field denote when the event occurred within the match.

Type of events

Goal events

We have two different goal events: GOAL when a goal is scored and OWN GOAL when an own goal is scored. With a goal event, the RELATED_PLAYER_ID will be the player who provided the assist for that goal.

Please note that the RELATED_PLAYER_ID can also be blank when no assist has been give.

Card events

We have three different card events:

  • YELLOWCARD when a player has received a yellow card.

  • REDCARD when a player has received a direct red card.

  • YELLOWREDCARD when a player has a received their second yellow card resulting in a red.

Penalty events

We have two different types of penalty events. Two for when a penalty happens during the game, those are: PENALTY for when the penalty has been scored and MISSED_PENALTY for when the penalty has been missed.

We also have penalty shootout events available. These are PENALTY_SHOOTOUT_MISS for when a penalty has been missed during a shootout, and PENALTY_SHOOTOUT_GOAL for when a penalty is scored during a shootout.

Substitutions

We only have 1 substitution event available as: SUBSTITUTION. The RELATED_PLAYER_ID for this event is the player who is coming off the field. The player going on the field is the PLAYER_ID.

VAR-events

At the moment we have the following VAR events:

  • VAR_CARD ​​Indicates that a VAR check was conducted for a potential card incident. The check aims to ensure the correctness of the decision made by the on-field officials regarding a player receiving a card.

  • Goal Disallowed When a goal is initially awarded by the on-field officials but is subsequently disallowed after a VAR review, this event type is recorded.

  • Penalty Disallowed Similar to Goal Disallowed, this event type is specific to penalties. It indicates that a penalty kick was initially awarded by the on-field officials but was later disallowed after a VAR revieW.

  • Penalty confirmed Contrary to Penalty Disallowed, this event type denotes that a penalty kick, initially awarded by the on-field officials, was confirmed and upheld after a VAR review.

  • Goal cancelled This event type is assigned when a goal, initially awarded by the on-field officials, is cancelled after a VAR review.

  • Goal confirmed In contrast to Goal Cancelled, this event type indicates that a goal, initially awarded by the on-field officials, was confirmed and upheld after a VAR review.

  • Goal under review When a VAR check is initiated for a potential goal-scoring situation, the event type is set to Goal Under Review. This indicates that the on-field officials have raised a question regarding the legitimacy of a goal, prompting a VAR review.

So, if a VAR check is related to a potential goal, the event type is initially set to Goal Under Review. Once the check is complete: If the goal is confirmed, the event type will be set to Goal Confirmed. If the goal is cancelled, the event type will be set to Goal Disallowed.

Extra includes

events.type

This include allows you to access more data about the specific type of event that occurred.

events.subType

This include allows you to access more detailed data related to an event, such as goals, that fall under a certain type. You can read more about subTypes here:

Tips and tricks

events.player

Interested in more information about the players related to the fixture event? Use the events.player include for detailed player information.

events.relatedPlayer

Similar to the include above this include will provide you with more information about the related player to this event.

Sort Order for Events

Each event is now assigned a numerical value in the sort_order field based on its occurrence. This feature is especially useful for ensuring that events like substitutions, goals, and VAR decisions are displayed in the correct chronological sequence. For instance, if multiple events of the same type happen in a match, the sort_order field will help you display them in the correct order, allowing for a clearer and more intuitive representation of match events. This is particularly helpful when analysing complex moments, such as multiple substitutions or VAR checks, to ensure that each event is placed correctly within the game flow.

Last updated