---
source_url: https://developer.sportradar.com/soccer/reference/soccer-extended-sport-event-extended-timeline
source_type: api_docs
upstream_version: Soccer Extended v4
crawled_at: 2026-08-31
---

# Sportradar Soccer Data Model

## IDs

Sportradar uses stable global IDs prefixed with `sr:`. Project code should store
these IDs, not display names.

| Entity | Example shape |
|---|---|
| Competition | `sr:competition:<id>` |
| Season | `sr:season:<id>` |
| Sport event / match | `sr:sport_event:<id>` |
| Competitor / team | `sr:competitor:<id>` |
| Player | `sr:player:<id>` |
| Venue | `sr:venue:<id>` |

Use mapping feeds when migrating between Soccer API versions, and player merge
mapping feeds when duplicate player profiles have been consolidated.

## Coverage Flags

Do not assume every match has every feed. Season and match responses include
coverage metadata that should drive UI fallbacks.

Important checks:

- whether the season/match has extended coverage;
- whether extended player stats are available;
- whether lineups and formation data are available;
- whether probabilities are part of the subscription;
- whether live timelines and push feeds are supported for the competition.

## Stage phase and phase_type

A season's stages carry `phase`, a coarse stage name such as `regular season`.
Several distinct stages share the same `phase` value: Apertura, Clausura and a
group stage can all arrive as `regular season`.

The OpenAPI specs (Soccer v4 and Soccer Extended v4, checked 2026-10-09) add
`phase_type` to the stage objects `season_stage` and `season_brackets_stage`. It is an enumerated, more granular stage type,
for example `apertura`, `clausura`, `group_stage`, `knockout_stage` or
`regular_season`. `phase` is unchanged for backward compatibility. Use `type`
plus `phase_type` as the key for a stage within a season, and fall back to
`phase` when `phase_type` is absent. The prose endpoint pages do not list
`phase_type` yet.

## Coordinates

Timeline event coordinates use a 0-100 pitch frame.

| Field | Meaning |
|---|---|
| `x` | horizontal event coordinate; `0` is at the home team's goal |
| `y` | vertical event coordinate; `0` is the top of the pitch when the home goal is on the left |
| `destination_x` | completed-pass end x coordinate |
| `destination_y` | completed-pass end y coordinate |
| `goalface_x` | shot goal-mouth x coordinate |
| `goalface_y` | shot goal-mouth y coordinate |

For charting, normalise these fields explicitly before mixing them with Opta,
StatsBomb, Wyscout, SkillCorner, or custom pitch coordinates.

## Timeline Event Fields

Extended timeline events contain both event identity and football semantics.
Useful chart/story fields include:

| Field | Notes |
|---|---|
| `type` | event type such as `goal_kick`, `period_start`, `yellow_card`; check enum docs for full list |
| `match_time` | match minute |
| `match_clock` | minute:second match clock |
| `stoppage_time` | added-time minute |
| `period` / `period_name` / `period_type` | period structure, extra time, penalties, pauses |
| `home_score` / `away_score` | score after the event |
| `competitor` | `home` or `away` |
| `counterattack` | boolean counterattack flag |
| `type_of_play` | shot context: set piece, open play, or individual |
| `xg_value` | xG value for a shot on goal |
| `body_type` | shot body part |
| `outcome` | event outcome, including on/off target, post, complete/incomplete, goal, saved |
| `additional_outcome` | shot detail such as hit woodwork, goal, saved, or goal prevented |
| `decision` / `description` | VAR decision state and outcome |

## Lineup and availability fields

These fields come from the Soccer v4 specification snapshot in
`specs/sportradar/soccer-v4-openapi.yaml`, fetched on 2026-08-31.

| Field | Where | Notes |
|---|---|---|
| `captain` | `player`, `lineup_player`, `base_lineup_player` | Boolean. Marks the captain in a lineup, so there is no need to infer it from armband events or squad metadata. |
| `estimated_return_date` | `player`, `lineup_player`, `base_lineup_player` | Date-time. The spec describes it as the estimated return date for the active player status, sourced from SDS `PlayerStatus.endTime`. |
| `estimated_return_date` | `missing_player` | Date-time. Estimated return date for a player listed as missing from the squad. |
| `is_friendly` | `coverage_competition_properties` | Boolean. Flags a competition as friendly, alongside the other coverage properties. |

Treat `estimated_return_date` as an estimate that moves, not a fixed fact. Store
the value with its retrieval time if you chart injury availability over a season.

## Player Event Details

Timeline events can attach players with activity types such as scorer, assist,
substituted in/out, fouler, fouled, passer, receiver, tackler, won by, lost by,
and shot taker. For event-to-player joins, use the `sr:player:*` ID and not only
the name.