Skip to main content
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

KeyDescription
shots_on_targetShots on target
shots_off_targetShots off target
attacksTotal attacks
dangerous_attacksDangerous attacks
possessionBall possession (percentage)
cornersCorner kicks
yellow_cardsYellow cards
red_cardsRed cards

​
Example

{
  "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

​
minute
string
required
The match minute at which the event occurred, e.g. "60" or "90+2".
​
type
string
required
The event type. See the table below.
​
team
string
required
Which team the event is associated with: "home", "away", or an empty string.
​
label
string
required
Human-readable description of the event.
​
score
string
The score at the time of the event, e.g. "1-0". Present for goal events; optional otherwise.
​
detail
string
Extra detail about the event (optional).

​
Event types

typeDescription
goalA goal was scored
cornerA corner kick was awarded
yellow_cardA yellow card was shown
red_cardA red card was shown
penaltyA penalty was awarded
substitutionA player substitution
eventA generic or uncategorized incident

​
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"}
]
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

​
x
number
Normalized x position, from 0 to 1, where 1 is the attacking end of the pitch.
​
y
number
Normalized y position, from 0 to 1.
​
event
string
The type of event associated with this position (optional), e.g. "goal".
​
minute
string
The match minute at which the position was recorded (optional).
​
detail
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.