ballCoordinates

What does the include do?

The ballCoordinates include allows users to track ball location on the pitch in real-time, essential for strategic analysis and fan engagement. Previously accessible via the metadata include, the standalone ballCoordinates include now provides faster, targeted access to ball-tracking data.

Why use Ball Coordinates?

This feature benefits:

• Betting insights: Helps assess whether a team is likely to score or gain a corner based on ball position.

• Offensive analysis: Quickly indicates which team is in an attacking position.

For deeper analysis, combine ballCoordinates with the Pressure Index to understand offensive and defensive pressures in real-time.

Requesting Ball Coordinates

To retrieve ball coordinates, use the following include in a fixture request:

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

Example: Track ball movements in a past fixture, such as the Champions League 2023 semi-final (ID: 18804445)

https://api.sportmonks.com/v3/football/fixtures/18804445?api_token=YOUR_TOKEN&include=ballCoordinates

Ball tracking has a slight delay (~15 seconds) but remains faster than live television data.

Interpreting X and Y values

• X-axis (length of the field): Range from 0.01 to 1.01.

• Y-axis (width of the field): Range from -0.02 to 1.02.

These values provide a normalised view of the ball’s exact position, making it compatible across different field sizes and orientations. To build a field display based on the x and y values provided by the Sportmonks ballCoordinates data, you’ll map the values to a coordinate system representing the pitch.

1. Define the field dimensions

The normalised x values range from 0.01 to 1.01, representing the length of the field (goal line to goal line).

The y values range from -0.02 to 1.02, covering the width (sideline to sideline).

1. Map coordinates:

Scale each x and y value to your field dimensions in pixels or meters.

For example, if the field is displayed as 1000 pixels wide, x = 0.51 would place the ball at 50% of the field length (500 pixels from one goal).

1. Set boundaries:

Use the provided ranges to map boundaries and draw sideline and goal areas at y = -0.02 to 1.02 and x = 0.01 to 1.01.