League Timeline

⏱️
Update Frequency
300s Time To Live / Cache

Data Points

Category & Sport

Attribute	Parent Element	Type	Description
`country_code`	`sport_event_context` - `category`	String	Country code for a sport event's category ex. `ENG` (England)
`id`	`sport_event_context` - `category`	String	Unique category ID for a sport event ex. `sr:category:1`
`name`	`sport_event_context` - `category`	String	Name for a sport event's category ex. `England` (Premier League)
`id`	`sport_event_context` - `sport`	String	Unique sport ID for a sport event ex. `sr:sport:1`
`name`	`sport_event_context` - `sport`	String	Name for a sport event's sport ex. `Soccer`

Competition

Attribute	Parent Element	Type	Description
`alternative_name`	`sport_event_context` - `competition`	String	Alternate name of a competition ex. `English Premier League` (instead of `Premier League`)
`gender`	`sport_event_context` - `competition`	String	Gender for a competition ex. `men`
`id`	`sport_event_context` - `competition`	String	Unique ID for a competition ex. `sr:competition:17` (Premier League)
`name`	`sport_event_context` - `competition`	String	Name of a competition ex. `Premier League`
`parent_id`	`sport_event_context` - `competition`	String	Unique parent ID for a competition. Typically present for group stage or playoff competitions ex. `sr:competition:945` used to link competitions together, like the World Cup and the various qualifiers.

Group

Attribute	Parent Element	Type	Description
`id`	`sport_event_context` - `groups` - `group`	String	Unique ID for a sport event's group ex. `sr:league:80253` (UEFA Euro 2024, Group D)
`name`	`sport_event_context` - `groups` - `group`	String	Name of a sport event's group ex. `UEFA Euro 2024, Group D`
`group_name`	`sport_event_context` - `groups` - `group`	String	Abbreviated name of a sport event's group ex. `D`

Round

Attribute	Parent Element	Type	Description
`competition_sport_event_number`	`sport_event_context` - `round`	Integer	Sport event number within a competition. Used for competitions that have fixed match numbers (World Cup)
`cup_round_id`	`sport_event_context` - `round`	String	Unique ID for a sport event's cup round ex. `sr:cup_round:1988995`
`cup_round_number_of_sport_events`	`sport_event_context` - `round`	Integer	Number of events in a sport event's round
`cup_round_sport_event_number`	`sport_event_context` - `round`	Integer	Number within the `cup_round` of a match ID. For example, 1st leg of 2
`name`	`sport_event_context` - `round`	String	Name of a sport event's round ex. `round_3` or `round_of_16`
`number`	`sport_event_context` - `round`	Integer	Number of a sport event's round
`other_sport_event_id`	`sport_event_context` - `round`	String	A linked sport event ID, typically in a two-legged tie ex. `sr:sport_event:47395897`

Season

Attribute	Parent Element	Type	Description
`competition_id`	`sport_event_context` - `season`	String	Unique ID for the competition a sport event belongs to ex. `sr:competition:17` (Premier League)
`disabled`	`sport_event_context` - `season`	Boolean	Signifies a season has been disabled when `true`
`end_date`	`sport_event_context` - `season`	Date	End date of a sport event's season ex. `2024-05-19`
`id`	`sport_event_context` - `season`	String	Unique ID for a sport event's season ex. `sr:season:105353` (Premier League 23/24)
`name`	`sport_event_context` - `season`	String	Name of a sport event's season ex. `Premier League 23/24`
`start_date`	`sport_event_context` - `season`	Date	Start date of a sport event's season ex. `2023-08-11`
`year`	`sport_event_context` - `season`	String	Year of a sport event's season ex. `23/24`

Stage

Attribute	Parent Element	Type	Description
`end_date`	`sport_event_context` - `stage`	Date	End date of a sport event's stage ex. `2024-05-19`
`order`	`sport_event_context` - `stage`	Integer	Order of a stage within a season
`phase`	`sport_event_context` - `stage`	String	Name of a sport event's stage ex. `regular season`, `preliminary_round`, `qualification`
`start_date`	`sport_event_context` - `stage`	Date	Start date of a sport event's stage ex. `2023-08-11`
`type`	`sport_event_context` - `stage`	String	Type of a sport event's stage `cup`, `league`
`year`	`sport_event_context` - `stage`	String	Year of a sport event's stage ex. `23/24`

Competitor

Attribute	Parent Element	Type	Description
`abbreviation`	`competitors` - `competitor`	String	Abbreviation for a competitor name ex. `LIV` (Liverpool FC)
`age_group`	`competitors` - `competitor`	String	Age group of a competitor, when applicable ex. `U23`
`country`	`competitors` - `competitor`	String	Country of a competitor ex. `England`
`country_code`	`competitors` - `competitor`	String	Country code of a competitor ex. `ENG` (England)
`gender`	`competitors` - `competitor`	String	Gender for a competitor `male`, `female`
`id`	`competitors` - `competitor`	String	Unique ID for a competitor ex. `sr:competitor:44` (Liverpool FC)
`name`	`competitors` - `competitor`	String	Name for a competitor ex. `Liverpool FC`
`qualifier`	`competitors` - `competitor`	String	Designation of a competitor for a sport event `home`, `away`
`virtual`	`competitors` - `competitor`	Boolean	Signifies a competitor is a virtual team whan `true`. Used for placeholder teams in TBD vs TBD matchups.

Player

Attribute	Parent Element	Type	Description
`id`	`statistics` - `competitor` - `player`	String	Unique ID of a player ex. `sr:player:159665`
`name`	`statistics` - `competitor` - `player`	String	Name of a player ex. `Salah, Mohamed`
`starter`	`statistics` - `competitor` - `player`	Boolean	Signifies a player is in the starting lineup for a sport event when `true`

Sport Event

Attribute	Parent Element	Type	Description
`count`	`sport_event_conditions` - `attendance`	Integer	Attendance for a sport event ex. `25078`
`neutral`	`sport_event_conditions` - `ground`	Boolean	Signifies a neutral ground sport event when `true`
`confirmed`	`sport_event_conditions` - `lineups`	Boolean	Signifies lineups for a sport event have been confirmed when `true`
`id`	`sport_event`	String	Unique ID of a sport event ex. `sr:sport_event:47395897`
`replaced_by`	`sport_event`	String	An alternative sport event ID if the match is postponed and played at a later date ex. `sr:sport_event:47395897`
`resume_time`	`sport_event`	Date	An updated timestamp if there is a delay at the start or interruption during a match ex. `2024-03-26T20:00:00+00:00`
`start_time`	`sport_event`	Date	Start time of a sport event ex. `2024-03-26T20:00:00+00:00`
`start_time_confirmed`	`sport_event`	Boolean	Signifies the start time of a sport event is confirmed when `true`
`overall_conditions`	`sport_event_conditions` - `weather`	String	Weather conditions for a sport event `good`, `medium`, `bad`, `indoor`, `extreme`
`pitch_conditions`	`sport_event_conditions` - `weather`	String	Pitch conditions for a sport event `good`, `medium`, `bad`

Sport Event - Channel

Attribute	Parent Element	Type	Description
`country`	`sport_event` - `channels` - `channel`	String	Country of a broadcast channel ex. `United States`
`country_code`	`sport_event` - `channels` - `channel`	String	Country code of a broadcast channel ex. `USA`
`name`	`sport_event` - `channels` - `channel`	String	Name of a broadcast channel ex. `Fox Soccer Plus`
`url`	`sport_event` - `channels` - `channel`	String	URL of a broadcast channel

Sport Event - Referee

Attribute	Parent Element	Type	Description
`id`	`sport_event_conditions` - `referees` - `referee`	String	Unique ID for a referee ex. `sr:referee:229470`
`name`	`sport_event_conditions` - `referees` - `referee`	String	Name of a referee ex. `Brooks, John`
`nationality`	`sport_event_conditions` - `referees` - `referee`	String	Nationality of a referee ex. `England`
`country_code`	`sport_event_conditions` - `referees` - `referee`	String	Country code of a referee ex. `ENG`
`type`	`sport_event_conditions` - `referees` - `referee`	String	Type of a referee ex. `first_assistant_referee`, `second_assistant_referee`, `fourth_official`, `video_assistant_referee`, `first_additional_assistant`, `second_additional_assistant`, `main_referee`

Sport Event - Coverage Properties

Attribute	Parent Element	Type	Description
`type`	`sport_event` - `coverage`	String	Type of coverage `sport_event`, `group`, `competition`
`ballspotting`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies ballspotting is available for a sport event when `true`
`basic_play_by_play`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies basic play-by-play is available for a sport event when `true`
`basic_player_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies basic player stats is available for a sport event when `true`
`basic_team_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies basic team stats is available for a sport event when `true`
`commentary`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies commentary is available for a sport event when `true`
`deeper_play_by_play`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies deeper play-by-play is available for a sport event when `true`
`deeper_player_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies deeper player stats is available for a sport event when `true`
`deeper_team_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies deeper team stats is available for a sport event when `true`
`extended_play_by_play`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies extended play-by-play data is available for a sport event when `true`. Access this data in the Sport Event Extended Timeline endpoint.
`extended_player_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies extended player stats is available for a sport event when `true`
`extended_team_stats`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies extended team stats is available for a sport event when `true`
`formations`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies team formations are available for a sport event when `true`
`fun_facts`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies fun facts are available for a sport event when `true`
`game_clock`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies the game clock is available for a sport event when `true`
`goal_scorers`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies goal scorers are available for a sport event when `true`
`goal_scorers_live`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies goal scorers are available live for a sport event when `true`
`lineups`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies goal lineups are available for a sport event when `true`
`lineups_availability`	`sport_event` - `coverage` - `sport_event_properties`	String	Describes the availability of lineups as pre-match or post-match `pre`, `post`
`probabilities`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies probabilities are available for a sport event when `true`
`scores`	`sport_event` - `coverage` - `sport_event_properties`	String	Describes the availability of scores as live or post-match `live`, `post`
`venue`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies venue info is available for a sport event when `true`

Sport Event Situation

Attribute	Parent Element	Type	Description
`played`	`sport_event_status` - `clock`	String	Match clock time in minutes `90:00`
`stoppage_time_played`	`sport_event_status` - `clock`	String	Stoppage time played in minutes `5:49`
`stoppage_time_announced`	`sport_event_status` - `clock`	String	Stoppage time announced in minutes `5:00`
`status`	`sport_event_status` - `match_situation`	String	Current situtation status of a match `safe`, `dangerous`, `attack`
`qualifier`	`sport_event_status` - `match_situation`	String	Defines the team in the current situation status `home`, `away`
`updated_at`	`sport_event_status` - `match_situation`	Date-Time	Timestamp of the most recent match situation update ex. `2024-04-14T14:57:28+00:00`
`away_score`	`sport_event_status` - `period_scores` - `period_score`	Integer	Away team period score
`home_score`	`sport_event_status` - `period_scores` - `period_score`	Integer	Home team period score
`number`	`sport_event_status` - `period_scores` - `period_score`	Integer	Period number
`type`	`sport_event_status` - `period_scores` - `period_score`	String	Period type `regular_period`, `overtime`, `penalties`, `pause`, `awaiting_extra`, `extra_time_halftime`, `interrupted`

Sport Event Status

Attribute	Parent Element	Type	Description
`aggregate_away_score`	`sport_event_status`	Integer	Aggregate score (of multiple sport events) for the away team
`aggregate_home_score`	`sport_event_status`	Integer	Aggregate score (of multiple sport events) for the home team
`aggregate_winner_id`	`sport_event_status`	String	Unique ID of the aggregate score winner ex. `sr:competitor:44`
`away_normaltime_score`	`sport_event_status`	Integer	Score for the away team in normal time
`away_overtime_score`	`sport_event_status`	Integer	Score for the away team in overtime
`away_score`	`sport_event_status`	Integer	Total score for the away team in the match
`home_normaltime_score`	`sport_event_status`	Integer	Score for the home team in normal time
`home_overtime_score`	`sport_event_status`	Integer	Score for the home team in overtime
`home_score`	`sport_event_status`	Integer	Total score for the home team in the match
`decided_by_fed`	`sport_event_status`	Boolean	Signifies a match result was decided by the federation when `true`. For example, incomplete due to crowd disruption
`match_status`	`sport_event_status`	String	Status within a match. Provides more detail on the state of a match when live than `status` ex. `not_started`, `2nd_half`, `ended`, `awaiting_penalties` See our FAQ for a complete list of statuses and their definitions.
`match_tie`	`sport_event_status`	Boolean	Signifies a match ended in a tie when `true`
`scout_abandoned`	`sport_event_status`	Boolean	Signifies a match was abandoned by a scout when `true`
`status`	`sport_event_status`	String	Status of a match ex. `not_started`, `live`, `ended`, `awaiting_penalties` See our FAQ for a complete list of statuses and their definitions.
`winner_id`	`sport_event_status`	String	Unique ID of the match winner ex. `sr:competitor:44`

Ball Location

Visit our FAQ for additional information on ball location data.

Attribute	Parent Element	Type	Description
`order`	`sport_event_status` - `ball_locations` - `ball_location`	Integer	Sequential order of a ball location event. The most recent location is `4` and the oldest location is `1`.
`qualifier`	`sport_event_status` - `ball_locations` - `ball_location`	String	Designation of a competitor for a ball location entry `home`, `away`
`x`	`sport_event_status` - `ball_locations` - `ball_location`	String	Horizontal X coordinate of the pitch. `x` is a number between `0` and `100`. The reference point `0` is at the home team’s goal.
`y`	`sport_event_status` - `ball_locations` - `ball_location`	String	Vertical Y coordinate of the pitch. `y` is a number between `0` and `100`. The reference point `0` is on the top of the pitch where the home team’s goal is on the left hand side.

Match Timeline

Attribute	Parent Element	Type	Description
`away_score`	`league_timeline` - `event`	Integer	Score for the away team after a timeline event
`break_name`	`league_timeline` - `event`	String	Brief description of a break event ex. `pause`
`card_descriptoin`	`league_timeline` - `event`	String	Description of the scenario during a card event ex. `pre_match`, `half_time`, `post_match`, `player_on_bench`, `first_half`, `second_half`, `during_penalty_shootout`
`text`	`league_timeline` - `event` - `commentary`	String	Description of the scenario during a card event Commentary text description of a timeline event ex. `Mario Hermoso (Atletico) has received a yellow card from Slavko Vincic.` or `It's a goal kick for the home team in Dortmund.`
`competitor`	`league_timeline` - `event`	String	Designation of a competitor for a timeline event `home`, `away`
`description`	`league_timeline` - `event`	String	Description of an event. This data point is not currently in use
`home_score`	`league_timeline` - `event`	Integer	Score for the home team after a timeline event
`id`	`league_timeline` - `event`	Integer	Unique ID for a timeline event ex. `1721786685`
`injury_time_announced`	`league_timeline` - `event`	Integer	Amount of injury time announced in minutes
`match_clock`	`league_timeline` - `event`	String	Match clock value for a timeline event, in minutes and seconds ex. `89:37`
`match_time`	`league_timeline` - `event`	Integer	Match clock value of a timeline event, in minutes ex. `89`
`method`	`league_timeline` - `event`	String	Method of a scored goal `penalty`, `own_goal`, `header`, `shot`, `free_kick`
`outcome`	`league_timeline` - `event`	String	Outcome of a missed goal `miss`, `post`, `bar`
`period`	`league_timeline` - `event`	Integer	Period number of a timeline event
`period_name`	`league_timeline` - `event`	String	Period name of a timeline event, appearing at the beginning of a period ex. `regular_period`
`period_type`	`league_timeline` - `event`	String	Period type of a timeline event `regular_period`, `overtime`, `penalties`, `pause`, `awaiting_extra`, `extra_time_halftime`, `interrupted`
`shootout_away_score`	`league_timeline` - `event`	Integer	Away team shootout score after a timeline event
`shootout_home_score`	`league_timeline` - `event`	Integer	Home team shootout score after a timeline event
`status`	`league_timeline` - `event`	String	Status available during penalty shootouts (`period_type="penalties"`) ex. `missed`, `scored`, `not_taken_yet`
`stoppage_time`	`league_timeline` - `event`	Integer	Stoppage time value for a timeline event ex. `3`
`stoppage_time_clock`	`league_timeline` - `event`	String	Stoppage time clock value for a timeline event ex. `2:03`
`type`	`league_timeline` - `event`	String	Type of timeline event. See our FAQ for a complete list of event types ex. `goal_kick`, `period_start`, `yellow_card`
`time`	`league_timeline` - `event`	Date-time	Timestamp of a timeline event ex. `2024-04-16T20:49:49+00:00`
`x`	`league_timeline` - `event`	Integer	Horizontal X coordinate of a timeline event. `x` is a number between `0` and `100`. The reference point `0` is at the home team’s goal.
`y`	`league_timeline` - `event`	Integer	Vertical Y coordinate of a timeline event. `y` is a number between `0` and `100`. The reference point `0` is on the top of the pitch where the home team’s goal is on the left hand side.

Player Event Details

Attribute	Parent Element	Type	Description
`id`	`event` - `player`	String	Unique player Id associated with a timeline event ex. `sr:player:2367105`
`name`	`event` - `player`	String	Player name associated with a timeline event ex. `Luna, Diego`
`type`	`event` - `player`	String	Player activity type associated with a timeline event. Signifies if a player scored a goal, recorded an assist, or participated in a substitution. ex. `scorer`, `assist`, `substituted_in`, `substituted_out`

Match Stats (Player)

Attribute	Parent Element	Type	Description
`assists`	`player` - `statistics`	Integer	Player assists for a match
`corner_kicks`	`player` - `statistics`	Integer	Player corner kicks for a match
`goals`	`player` - `statistics`	Integer	Player goals scored for a match
`offsides`	`player` - `statistics`	Integer	Player offsides for a match
`own_goals`	`player` - `statistics`	Integer	Player own goals for a match
`red_cards`	`player` - `statistics`	Integer	Player red cards for a match
`substituted_in`	`player` - `statistics`	Integer	Signifies a player was substituted in during a match when `1`
`substituted_out`	`player` - `statistics`	Integer	Signifies a player was substituted out during a match when `1`
`yellow_cards`	`player` - `statistics`	Integer	Player yellow cards for a match
`yellow_red_cards`	`player` - `statistics`	Integer	Player red cards for a match resulting from two yellow cards

Match Stats (Team)

Attribute	Parent Element	Type	Description
`assists`	`competitor` - `statistics`	Integer	Total team assists for a match
`corner_kicks`	`competitor` - `statistics`	Integer	Total team corner kicks for a match
`goals`	`competitor` - `statistics`	Integer	Team goals for a match
`red_cards`	`competitor` - `statistics`	Integer	Total team red cards for a match
`shots_on_goal`	`competitor` - `statistics`	Integer	Total team shots on goal for a match
`substitutions`	`competitor` - `statistics`	Integer	Total number player subsitutions in a match
`yellow_cards`	`competitor` - `statistics`	Integer	Total team yellow cards for a match
`yellow_red_cards`	`competitor` - `statistics`	Integer	Total team red cards for a match which resulted from two yellow cards

Venue

Attribute	Parent Element	Type	Description
`capacity`	`venue`	Integer	Capacity of a venue ex. `60000`
`changed`	`venue`	Boolean	Signifies a venue has been changed when `true`
`city_name`	`venue`	String	City name of a venue ex. `Liverpool`
`country_code`	`venue`	String	Country code of a venue ex. `ENG` (England)
`country_name`	`venue`	String	Country name of a venue ex. `England`
`id`	`venue`	String	Unique ID of a venue ex. `sr:venue:579`
`map_coordinates`	`venue`	String	Coordinates of a venue ex. `53.430622,-2.960919`
`name`	`venue`	String	Name of a venue ex. `Anfield`
`reduced_capacity`	`venue`	Boolean	Optional attribute signifying a venue has a restricted capacity when `true`
`reduced_capacity_max`	`venue`	Integer	Value of a venue's restricted capacity
`timezone`	`venue`	String	Timezone of a venue ex. `Europe/London`