Soccer Extended Push Events provides real-time event updates for all live matches.
Syntax
| https://api.sportradar.com/soccer-extended/{access_level}/{version}/stream/events/subscribe |
Parameters
| Parameter | Description |
|---|---|
access_level | Defines the access level of your API keyproduction, trial |
version | Version number of the APIv4 |
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.
Each query string parameter can be added with a preceding ampersand (&).
| 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 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-extended/trial/v4/stream/events/subscribe")
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)
request["x-api-key"] = "{your_api_key}" # Replace with your actual key
response = http.request(request)
puts response.read_bodyimport requests
import json
headers = {
'x-api-key': 'your_api_key' # Replace with your actual key
}
r = requests.get(
"https://api.sportradar.com/soccer-extended/trial/v4/stream/events/subscribe",
headers=headers,
allow_redirects=False
)
redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True, headers=headers)
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 -X GET 'https://api.sportradar.com/soccer-extended/trial/v4/stream/events/subscribe' \
-H 'x-api-key: {your_api_key}'Samples with Query String Params
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.com/soccer-extended/trial/v4/stream/events/subscribe?&format=json&sport_event_id=sr:sport_event: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)
request["x-api-key"] = "{your_api_key}" # Replace with your actual key
response = http.request(request)
puts response.read_bodyimport requests
import json
headers = {
'x-api-key': 'your_api_key' # Replace with your actual key
}
r = requests.get("https://api.sportradar.com/soccer-extended/trial/v4/stream/events/subscribe",
params = {'format': 'json', 'sport_event_id': 'sr:sport_event: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 -X GET 'api.sportradar.com/soccer-extended/trial/v4/stream/events/subscribe?&format=json&sport_event_id=sr:sport_event:13468929'
-H 'x-api-key: {your_api_key}'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-extended |
competition_id | metadata | String | Unique Id of a competition ex. sr:competition:23 |
event_id | metadata | String | Description of a push timeline eventmatch_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 responsejson, 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-extended-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_description | 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 |
competitor | event | String | Designation of a competitor for a timeline eventhome, away |
decision | timeline - event | String | Decision of a VAR timeline eventpending, cancelled, upheld, overturnedNot currently supported |
description | timeline - event | String | Result of a VAR timeline eventgoal, penalty, red_card, no_goal, no_penalty, no_red_card, corner, no_corner, mistaken_identity, no_mistaken_identity |
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 |
late | league_timeline - event | Boolean | Indicates the incoming substitute was temporarily prevented from entering the field because the replaced player did not leave the field within the time allowed. When true, the team briefly plays with one fewer player before the substitution is completed. |
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 goalpenalty, own_goal, header, shot, free_kick, corner |
outcome | event | String | Outcome of a missed goalmiss, 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 eventregular_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 |
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 | UTC timestamp indicating when the timeline event was created or most recently updated in our system. This reflects system processing time, not the time the event occurred on the pitch. The timestamp may lag behind the actual event—typically by a short interval during live play, or by minutes to hours for later additions and corrections. When the record is first created, this value reflects its creation time. If the record is later updated, the value is replaced with the latest update time and no longer preserves the original creation time. 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 statusex. not_started, 2nd_half, ended, awaiting_penaltiesSee 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_penaltiesSee 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 entryhome, 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 minutes90:00 |
stoppage_time_played | sport_event_status - clock | String | Stoppage time played in minutes5:49 |
stoppage_time_announced | sport_event_status - clock | String | Stoppage time announced in minutes5:00 |
status | sport_event_status - match_situation | String | Current situation status of a matchsafe, dangerous, attack |
qualifier | sport_event_status - match_situation | String | Defines the team in the current situation statushome, 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 typeregular_period, overtime, penalties, pause, awaiting_extra, extra_time_halftime, interrupted |
