Match Events, Statistics, and Ball Position Reference

The stats, events, and ball fields of the live snapshot give you a detailed picture of everything happening in a match. This page documents their structure and the values you can expect to encounter.

Statistics

The stats field is a map of stat key → per-side integers:

{"home": int, "away": int}

Treat the map as open-ended — the set of keys present depends on the sport and what the data provider reports for a given match. Iterate over the keys you receive rather than assuming a fixed set.

Common soccer stat keys

Integer counters, in stats:

Key	Description
`shots_on_target`	Shots on target
`shots_off_target`	Shots off target
`attacks`	Total attacks
`dangerous_attacks`	Dangerous attacks
`possession`	Ball possession (percentage)
`corners`	Corner kicks
`yellow_cards`	Yellow cards
`red_cards`	Red cards
`throw_ins`	Throw-ins
`free_kicks`	Free kicks
`goal_kicks`	Goal kicks
`penalties`	Penalties awarded
`substitutions`	Player substitutions
`keeper_saves`	Goalkeeper saves
`key_passes`	Key passes
`crosses`	Crosses

Fractional stat keys

Some stats are naturally percentages or ratios and are delivered as floats under the separate top-level stats_float map (same {"home": float, "away": float} shape):

Key	Description
`passing_accuracy`	Passing accuracy (`0–1`)
`crossing_accuracy`	Crossing accuracy (`0–1`)
`action_area`	Share of play in the attacking third (percentage)

Integer counters, in stats:

Key	Description
`shots_on_target`	Shots on target
`shots_off_target`	Shots off target
`attacks`	Total attacks
`dangerous_attacks`	Dangerous attacks
`possession`	Ball possession (percentage)
`corners`	Corner kicks
`yellow_cards`	Yellow cards
`red_cards`	Red cards
`throw_ins`	Throw-ins
`free_kicks`	Free kicks
`goal_kicks`	Goal kicks
`penalties`	Penalties awarded
`substitutions`	Player substitutions
`keeper_saves`	Goalkeeper saves
`key_passes`	Key passes
`crosses`	Crosses

Fractional stat keys

Some stats are naturally percentages or ratios and are delivered as floats under the separate top-level stats_float map (same {"home": float, "away": float} shape):

Key	Description
`passing_accuracy`	Passing accuracy (`0–1`)
`crossing_accuracy`	Crossing accuracy (`0–1`)
`action_area`	Share of play in the attacking third (percentage)

Examplexample

{
  "shots_on_target": {"home": 4, "away": 2},
  "possession": {"home": 56, "away": 44}
}

Events

The events field is an array of timeline incidents recorded during the match. It may be null if no events have occurred yet.

Event fields

{
  "shots_on_target": {"home": 4, "away": 2},
  "possession": {"home": 56, "away": 44}
}

Events

The events field is an array of timeline incidents recorded during the match. It may be null if no events have occurred yet.

Event fields

string

required

The match minute at which the event occurred, e.g. "60" or "90+2". Empty for shootout events, which have no match minute — see Shootout events. Empty for shootout events, which have no match minute — see Shootout eventsmatch minute at which the event occurred, e.g. "60" or "90+2". Empty for shootout events, which have no match minute — see Shootout events. Empty for shootout events, which have no match minute — see Shootout events.

string

required

The event type. See the table belowThe event type. See the table below.

string

required

Which team the event is associated with: "home", "away", or an empty string.

string

required

Human-readable description of the event.

string

The score at the time of the event, e.g. "1-0". Present for goal events; optional otherwise.

string

Extra detail about the event (optional). For shootout events this is "scored" or "missed" — see Shootout events. For shootout events this is "scored" or "missed" — see Shootout events.

string

Player name, properly spaced (optional). Present on incidents where the provider identifies the player involved.

boolean

true for the entries the provider highlights — goals, cards, and period markers (optional). Use it to pick out headline moments without hard-coding a list of types.

string

Video-replay id (optional). A non-empty value means a clip exists for this incident.

Event types

`type`	Description	`detail` values	`detail` values
`goal`	A goal was scored	—	—
`corner`	A corner kick was awarded	—	—
`yellow_card`	A yellow card was shown	—	—
`red_card`	A red card was shown	—	—
`penalty`	A penalty was awarded	—	—
`substitution`	A player substitution	—	—
`shot_on_target`	A shot on target	—
`shot_off_target`	A shot off target	—
`offside`	An offside call	—
`assist`	A recorded assist	—
`period_score`	HT / FT / AET score marker (neutral, no `team`)	—
`shootout`	A penalty-shootout kick	`scored`, `missed`
`shootout`	A penalty-shootout kick	`scored`, `missed`
`event`	A generic or uncategorized incident	—	—

Treat any unrecognized type value as event.

string

required

Which team the event is associated with: "home", "away", or an empty string.

string

required

Human-readable description of the event.

string

The score at the time of the event, e.g. "1-0". Present for goal events; optional otherwise.

string

Player name, properly spaced (optional). Present on incidents where the provider identifies the player involved.

boolean

true for the entries the provider highlights — goals, cards, and period markers (optional). Use it to pick out headline moments without hard-coding a list of types.

string

Video-replay id (optional). A non-empty value means a clip exists for this incident.

Event types

`type`	Description	`detail` values	`detail` values
`goal`	A goal was scored	—	—
`corner`	A corner kick was awarded	—	—
`yellow_card`	A yellow card was shown	—	—
`red_card`	A red card was shown	—	—
`penalty`	A penalty was awarded	—	—
`substitution`	A player substitution	—	—
`shot_on_target`	A shot on target	—
`shot_off_target`	A shot off target	—
`offside`	An offside call	—
`assist`	A recorded assist	—
`period_score`	HT / FT / AET score marker (neutral, no `team`)	—
`shootout`	A penalty-shootout kick	`scored`, `missed`
`shootout`	A penalty-shootout kick	`scored`, `missed`
`event`	A generic or uncategorized incident	—	—

Treat any unrecognized type value as event.

Shootout eventsShootout events

When a match goes to a penalty shootout, each kick is emitted as its own event with type: "shootout" and a detail of either "scored" or "missed". Shootout kicks have no match minute, so minute is an empty string; they are ordered after all timed events, including extra time, in the order they were taken (home kicker before away kicker within each round). The top-level score.home and score.away stay at the post-extra-time result — use score.shootout on the snapshot to read the per-side kick tally and determine the winner. The phase can also decode to "Shootout score" (code 0008) while the shootout is in progress.

{"minute": "", "type": "shootout", "team": "home", "label": "Shootout score", "detail": "scored"}

Example events array

{"minute": "", "type": "shootout", "team": "home", "label": "Shootout score", "detail": "scored"}

Example events array

[
  {"minute": "45+5", "type": "goal", "team": "home", "label": "Goal", "score": "1-0"},
  {"minute": "60", "type": "yellow_card", "team": "away", "label": "Yellow Card"},
  {"minute": "90+2", "type": "goal", "team": "away", "label": "Goal", "score": "1-1"},
  {"minute": "", "type": "shootout", "team": "home", "label": "Shootout score", "detail": "scored"},
  {"minute": "", "type": "shootout", "team": "away", "label": "Shootout score", "detail": "missed"},
  {"minute": "", "type": "shootout", "team": "home", "label": "Shootout score", "detail": "scored"},
  {"minute": "", "type": "shootout", "team": "away", "label": "Shootout score", "detail": "missed"}
]

The events array in a full_time result snapshot includes the complete match timeline from kick-off to the final whistle.

Ball position

The ball field contains the last event-anchored position of the ball on the pitch. It is updated whenever a notable event is recorded and reflects where that event took place.

Ball position fields

number

Normalized x position, from 0 to 1, where 1 is the attacking end of the pitch.

number

Normalized y position, from 0 to 1.

string

The type of event associated with this position (optional), e.g. "goal".

string

The match minute at which the position was recorded (optional).

string

Extra detail about the event at this position (optional).

Use the normalized x and y coordinates to render a ball position overlay on a pitch graphic. Because both values are in the 0–1 range, you can multiply directly by your canvas width and height.

REST API

WebSocket

Data Schemas

Match Events, Statistics, and Ball Position Reference

Statistics

Common soccer stat keys

Fractional stat keys

Fractional stat keys

Examplexample

Events

Event fields

Events

Event fields

Event types

Event types

Shootout eventsShootout events

Example events array

Example events array

Ball position

Ball position fields

​Statistics

​Common soccer stat keys

​Fractional stat keys

​Fractional stat keys

​Examplexample

​Events

​Event fields

​Events

​Event fields

​Event types

​Event types

​Shootout eventsShootout events

​Example events array

​Example events array

​Ball position

​Ball position fields

Statistics

Common soccer stat keys

Fractional stat keys

Fractional stat keys

Examplexample

Events

Event fields

Events

Event fields

Event types

Event types

Shootout eventsShootout events

Example events array

Example events array

Ball position

Ball position fields