> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Match Events, Statistics, and Ball Position Reference

> Reference for the events timeline, statistics map, and ball position in Sportrix Data live snapshots. Covers event types and common soccer stat keys.

The `stats`, `events`, and `ball` fields of the [live snapshot](/api/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**:

```json theme={null}
{"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

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

### Example

```json theme={null}
{
  "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

<ResponseField name="minute" type="string" required>
  The match minute at which the event occurred, e.g. `"60"` or `"90+2"`.
</ResponseField>

<ResponseField name="type" type="string" required>
  The event type. See the table below.
</ResponseField>

<ResponseField name="team" type="string" required>
  Which team the event is associated with: `"home"`, `"away"`, or an empty string.
</ResponseField>

<ResponseField name="label" type="string" required>
  Human-readable description of the event.
</ResponseField>

<ResponseField name="score" type="string">
  The score at the time of the event, e.g. `"1-0"`. Present for goal events; optional otherwise.
</ResponseField>

<ResponseField name="detail" type="string">
  Extra detail about the event (optional).
</ResponseField>

### Event types

| `type`         | Description                         |
| -------------- | ----------------------------------- |
| `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               |
| `event`        | A generic or uncategorized incident |

### Example events array

```json theme={null}
[
  {"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"}
]
```

<Note>
  The `events` array in a `full_time` result snapshot includes the **complete match timeline** from kick-off to the final whistle.
</Note>

## 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

<ResponseField name="x" type="number">
  Normalized x position, from `0` to `1`, where `1` is the attacking end of the pitch.
</ResponseField>

<ResponseField name="y" type="number">
  Normalized y position, from `0` to `1`.
</ResponseField>

<ResponseField name="event" type="string">
  The type of event associated with this position (optional), e.g. `"goal"`.
</ResponseField>

<ResponseField name="minute" type="string">
  The match minute at which the position was recorded (optional).
</ResponseField>

<ResponseField name="detail" type="string">
  Extra detail about the event at this position (optional).
</ResponseField>

<Tip>
  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.
</Tip>