Push Events

Syntax

https://api.sportradar.com/soccer/{access_level}/{version}/stream/events/subscribe?api_key={your_api_key}

Parameters

Parameter	Description
`access_level`	Defines the access level of your API key `production`, `trial`
`version`	Version number of the API `v4`
`your_api_key`	Your API key

Optional Query String Parameters

By default, a Push feed will provide all data available for all in progress games. If needed, you can filter the data returned by including query strings.

Optional query string parameters must be added after your API key with an ampersand (&). If you are filtering for more than one result, separate the results with a comma (,) and no spaces.

URL Parameters	Description
`competition_id`	Competition id Example: `competition_id=sr:competition:204`
`event_id`	Event type Example: `event_id=free_kick`
`format`	Format type `json`, `xml` Example: `format=json`
`season_id`	Season id Example: `season_id=sr:season:50039`
`sport_event_id`	Sport event id Example: `sport_event_id=sr:sport_event_id:13644241`

Code Samples

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe?api_key={your_api_key}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests
import json

r = requests.get("https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe",
    params = {'api_key': 'your_api_key'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

curl -L "GET api.sportradar.com/soccer/trial/v4/stream/events/subscribe?api_key={your_api_key}"

Samples with Query String Params

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe?api_key={your_api_key}&format=json&sport_event_id=sr:match:13468929")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests
import json

r = requests.get("https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe",
    params = {'api_key': 'your_api_key', 'format': 'json', 'sport_event_id': 'sr:match:13468929'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

curl -L GET 'https://api.sportradar.com/soccer/trial/v4/stream/events/subscribe?api_key={your_api_key}&format=json&sport_event_id=sr:match:13468929'

Response Sample

The above commands return json like this.

Data Points

Metadata:

Attribute	Parent Element	Type	Description
`channel`	`metadata`	String	Sport of the stream connection ex. `soccer`
`competition_id`	`metadata`	String	Unique Id of a competition ex. `sr:competition:23`
`event_id`	`metadata`	String	Description of a push timeline event `match_started`, `match_ended`, `period_start`, `period_score`, `score_change`, `yellow_card`, `yellow_red_card`, `red_card`, `substitution`, `injury_time_shown`, `free_kick`, `goal_kick`, `throw_in`, `offside`, `corner_kick`, `shot_on_target`, `shot_off_target`, `save`, `injury`, `penalty_kick`, `player_back_from_injury`, `penalty_missed`, `penalty_shootout`, `decision_to_var`, `decision_to_var_over`, `possible_decision_to_var`, `canceled_decision_to_var`, `break_start`, `injury_return`, `video_assistant_referee`, `video_assistant_referee_over`, `penalty_awarded`, `shot_saved, possible_goal`
`format`	`metadata`	String	Format type of the response `json`, `xml`
`season_id`	`metadata`	String	Unique Id of a season ex. `sr:season:106499`
`sport_event_id`	`metadata`	String	Unique Id of a sport event ex. `sr:sport_event_id:42134765`
`sport_id`	`metadata`	String	Unique Id of a sport ex. `sr:sport:1`
`from`	`heartbeat`	Integer	Unix timestamp of the beginning of a heartbeat message ex. `1713804799`
`to`	`heartbeat`	Integer	Unix timestamp of the end of a heartbeat message ex. `1713804804`
`interval`	`heartbeat`	Integer	Interval of a heartbeat message in seconds
`type`	`heartbeat`	String	Type of heartbeat message ex. `events`, `statistics`
`package`	`heartbeat`	String	Package of a heartbeat message ex. `soccer-v4`

Match Timeline:

Attribute	Parent Element	Type	Description
`away_score`	`event`	Integer	Score for the away team after a timeline event
`break_name`	`event`	String	Brief description of a break event ex. `pause`
`card_descriptoin`	`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`	`event` - `commentaries`	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`	`event`	String	Designation of a competitor for a timeline event `home`, `away`
`description`	`event`	String	Description of an event. This data point is not currently in use
`home_score`	`event`	Integer	Score for the home team after a timeline event
`id`	`event`	Integer	Unique ID for a timeline event ex. `1721786685`
`injury_time_announced`	`event`	Integer	Amount of injury time announced in minutes
`match_clock`	`event`	String	Match clock value for a timeline event, in minutes and seconds ex. `89:37`
`match_time`	`event`	Integer	Match clock value of a timeline event, in minutes ex. `89`
`method`	`event`	String	Method of a scored goal `penalty`, `own_goal`, `header`, `shot`, `free_kick`
`outcome`	`event`	String	Outcome of a missed goal `miss`, `post`, `bar`
`period`	`event`	Integer	Period number of a timeline event
`period_name`	`event`	String	Period name of a timeline event, appearing at the beginning of a period ex. `regular_period`
`period_type`	`event`	String	Period type of a timeline event `regular_period`, `overtime`, `penalties`, `pause`, `awaiting_extra`, `extra_time_halftime`, `interrupted`
`shootout_away_score`	`event`	Integer	Away team shootout score after a timeline event
`shootout_home_score`	`event`	Integer	Home team shootout score after a timeline event
`shootout_home_score`	`event`	Integer	Home team shootout score after a timeline event
`status`	`event`	String	Status available during penalty shootouts (`period_type="penalties"`) ex. `missed`, `scored`, `not_taken_yet`
`stoppage_time`	`event`	Integer	Stoppage time value for a timeline event ex. `3`
`stoppage_time_clock`	`event`	String	Stoppage time clock value for a timeline event ex. `2:03`
`type`	`event`	String	Type of timeline event. See our FAQ for a complete list of event types ex. `goal_kick`, `period_start`, `yellow_card`
`time`	`event`	Date-time	Timestamp of a timeline event ex. `2024-04-16T20:49:49+00:00`
`updated`	`event`	Boolean	Signifies this event has been updated since its original entry when `true`
`updated_time`	`event`	Date-time	Timestamp of an updated time entry ex. `2024-04-22T17:17:24+00:00`
`x`	`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`	`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` - `players`	String	Unique player Id associated with a timeline event ex. `sr:player:2367105`
`name`	`event` - `players`	String	Player name associated with a timeline event ex. `Luna, Diego`
`type`	`event` - `players`	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`

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
`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`
`scount_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`, `2nd_half`, `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.

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`	Integer	Away team period score
`home_score`	`sport_event_status` - `period_scores`	Integer	Home team period score
`number`	`sport_event_status` - `period_scores`	Integer	Period number
`type`	`sport_event_status` - `period_scores`	String	Period type `regular_period`, `overtime`, `penalties`, `pause`, `awaiting_extra`, `extra_time_halftime`, `interrupted`