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.

How to use this include

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

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

How does it work?

The events include provides comprehensive information about every significant moment during a match.

Core fields in the response:

• id: Unique identifier for the event

• fixture_id: The fixture (match) this event belongs to

• period_id: The period when the event occurred

• team_id: The team involved in the event

• player_id: The player involved in the event

• related_player_id: Secondary player (e.g., assist provider, player coming off in substitution)

• player_name: Name of the primary player

• related_player_name: Name of the related player

• minute: When during the match the event occurred

• extra_minute: Additional minutes (injury time) if applicable

• result: The match score at the time of the event (when applicable)

• info: Details about the event (e.g., "Header", "Foul", "Offside check")

• sort_order: Critical - Chronological ordering of events. Always use this to sort events, not the minute field

Types of events

Goal events

GOAL - When a goal is scored during play

• player_id = Goal scorer

• related_player_id = Assist provider (can be null if unassisted)

• result = Updated match score

OWN GOAL - When a defensive error results in an own goal

• player_id = Player making the error

• result = Updated match score

Card events

YELLOWCARD - Player receives a yellow card

• player_id = Player receiving the card

• info = Reason (e.g., "Foul", "Unsporting behaviour")

REDCARD - Player receives a direct red card

• player_id = Player receiving the card

• Results in immediate ejection

YELLOWREDCARD - Second yellow card resulting in red

• player_id = Player receiving second yellow

• Automatic ejection

Penalty events

PENALTY - Penalty goal scored during play

• player_id = Penalty taker

• result = Updated match score

MISSED_PENALTY - Penalty missed or saved

• player_id = Penalty taker

PENALTY_SHOOTOUT_GOAL - Goal during penalty shootout

• player_id = Penalty taker

• result = Shootout score

PENALTY_SHOOTOUT_MISS - Missed penalty in shootout

• player_id = Penalty taker

Substitution events

SUBSTITUTION - Player substitution

• player_id = Player coming ON the field

• related_player_id = Player coming OFF the field

• Important: These are reversed from some other events

VAR events

GOAL_UNDER_REVIEW - VAR check initiated for a goal

• Indicates a goal is being reviewed

• Followed by either GOAL_CONFIRMED or GOAL_DISALLOWED

GOAL_CONFIRMED - Goal upheld after VAR review

• Initially awarded goal confirmed as valid

GOAL_DISALLOWED / GOAL_CANCELLED - Goal cancelled by VAR

• Initial goal is disallowed

• Usually due to offside, foul, or handball

VAR_CARD - VAR review of a card incident

• Indicates VAR reviewed a potential card decision

PENALTY_CONFIRMED - Penalty upheld after VAR review

• Initially awarded penalty confirmed

PENALTY_DISALLOWED - Penalty cancelled by VAR

• Initial penalty decision reversed

Important: Using sort_order for correct event sequencing

Always sort events by sort_order, not minute. Multiple events can occur at the same minute, but sort_order ensures they are displayed in correct chronological sequence.

// Correct
events = events.sort((a, b) => a.sort_order - b.sort_order);

// Incorrect (may mess up sequence)
// events = events.sort((a, b) => a.minute - b.minute);

VAR Event Chains Example

Multiple related events can occur in sequence. For instance, when a goal is reviewed:

1. Minute 54 (sort_order: 15): GOAL event - Goal is initially scored

2. Minute 54 (sort_order: 16): GOAL_UNDER_REVIEW - VAR check initiated

3. Minute 54 (sort_order: 17): GOAL_DISALLOWED - VAR cancels the goal

All three events share the same minute but differ in sort_order. This is why sorting by sort_order is critical.

Handling null values

related_player_id can be null when:

• A goal is scored with no assist

• A card is issued (no secondary player)

• Most non-substitution events

result is null for:

• Card events

• Substitutions

• VAR reviews (until decision)

extra_minute is null for:

• Events before injury time

Handle gracefully in your code:

assist = event.related_player_name ? `(${event.related_player_name})` : "";
score = event.result || "Match ongoing";
time_str = event.extra_minute ? `${event.minute}+${event.extra_minute}'` : `${event.minute}'`;

Example responses

Goal with assist

{
  "id": 152213481,
  "fixture_id": 19568543,
  "period_id": 6379831,
  "team_id": 3321,
  "player_id": 160208,
  "related_player_id": 37912237,
  "player_name": "Alejandro Grimaldo",
  "related_player_name": "Christian Kofane",
  "result": "1-0",
  "info": "Left foot shot",
  "minute": 23,
  "extra_minute": null,
  "sort_order": 1
}

Substitution event

{
  "id": 152214074,
  "fixture_id": 19568543,
  "period_id": 6379936,
  "team_id": 9,
  "player_id": 336133,
  "related_player_id": 37459073,
  "player_name": "Phil Foden",
  "related_player_name": "Rico Lewis",
  "minute": 46,
  "extra_minute": null,
  "sort_order": 2
}

Yellow card event

{
  "id": 152214396,
  "fixture_id": 19568543,
  "period_id": 6379936,
  "team_id": 3321,
  "player_id": 160208,
  "related_player_id": null,
  "player_name": "Alejandro Grimaldo",
  "related_player_name": null,
  "info": "Foul",
  "minute": 60,
  "extra_minute": null,
  "sort_order": 5,
  "rescinded": false
}

Other include options

In addition to the events include, you can use nested includes to retrieve more detailed data. For more information about nested includes, see this page.

The following nested includes are commonly used with events:

events.type - Returns detailed type information for each event

• Provides event classification and metadata

• Minimal size increase

events.subType - Returns detailed event sub-type information

• For example, the specific type of shot (header, left foot, right foot)

• Useful for detailed shooting analysis

events.player - Returns full player information for the primary player

• Includes player profile, nationality, physical attributes

• Increases response size significantly

events.relatedPlayer - Returns full player information for the secondary player

• For assist providers, players coming off, etc.

• Increases response size significantly

Example combined request:

?include=events.type,events.player,events.relatedPlayer

This would provide event types, full player details for both the primary and secondary players in a single request.

Best practices

1. Always sort by sort_order: This ensures correct event sequencing, especially when multiple events occur at the same match minute.

2. Use nested includes sparingly: Adding player includes significantly increases response size. Only include what you need.

3. Handle VAR event chains: Expect that VAR-related events come in sequences. Don't assume a GOAL event is final, check for subsequent VAR events.

4. Check for null fields: Always validate related_player_id, result, extra_minute, and info before using them.

5. Cache completed matches: Once a match reaches final state, events don't change. Cache these responses permanently.

Related includes

• States - Current match state works alongside events to give context

• Periods - Period information complements event data

• Lineups - Cross-reference players with lineup data

• Participants - Team information relevant to events