Integration GuidesDocs
Coverage MatrixDocumentationChange LogLog InContact Us
Docs

Push Events

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

ParameterDescription
access_levelDefines the access level of your API key

production, trial
versionVersion number of the API

v4
🔐

Authorization

Place your API key in the header for each request (x-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.

Each query string parameter can be added with a preceding ampersand (&).

URL ParametersDescription
competition_idCompetition id

Example: competition_id=sr:competition:204
event_idEvent type

Example: event_id=free_kick
formatFormat type

Example: format=json
season_idSeason id

Example: season_id=sr:season:50039
sport_event_idSport 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_body
import 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_body
import 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
AttributeParent ElementTypeDescription
channelmetadataStringSport of the stream connection

ex. soccer-extended
competition_idmetadataStringUnique Id of a competition

ex. sr:competition:23
event_idmetadataStringDescription 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
formatmetadataStringFormat type of the response

json, xml
season_idmetadataStringUnique Id of a season

ex. sr:season:106499
sport_event_idmetadataStringUnique Id of a sport event

ex. sr:sport_event_id:42134765
sport_idmetadataStringUnique Id of a sport

ex. sr:sport:1
fromheartbeatIntegerUnix timestamp of the beginning of a heartbeat message

ex. 1713804799
toheartbeatIntegerUnix timestamp of the end of a heartbeat message

ex. 1713804804
intervalheartbeatIntegerInterval of a heartbeat message in seconds
typeheartbeatStringType of heartbeat message

ex. events, statistics
packageheartbeatStringPackage of a heartbeat message

ex. soccer-extended-v4
Match Timeline
AttributeParent ElementTypeDescription
away_scoreeventIntegerScore for the away team after a timeline event
break_nameeventStringBrief description of a break event

ex. pause
card_descriptoineventStringDescription of the scenario during a card event

ex. pre_match, half_time, post_match, player_on_bench, first_half, second_half, during_penalty_shootout
competitoreventStringDesignation of a competitor for a timeline event

home, away
descriptioneventStringDescription of an event.

This data point is not currently in use
home_scoreeventIntegerScore for the home team after a timeline event
ideventIntegerUnique ID for a timeline event

ex. 1721786685
injury_time_announcedeventIntegerAmount of injury time announced in minutes
match_clockeventStringMatch clock value for a timeline event, in minutes and seconds

ex. 89:37
match_timeeventIntegerMatch clock value of a timeline event, in minutes

ex. 89
methodeventStringMethod of a scored goal

penalty, own_goal, header, shot, free_kick, corner
outcomeeventStringOutcome of a missed goal

miss, post, bar
periodeventIntegerPeriod number of a timeline event
period_nameeventStringPeriod name of a timeline event, appearing at the beginning of a period

ex. regular_period
period_typeeventStringPeriod type of a timeline event

regular_period, overtime, penalties, pause, awaiting_extra, extra_time_halftime, interrupted
shootout_away_scoreeventIntegerAway team shootout score after a timeline event
shootout_home_scoreeventIntegerHome team shootout score after a timeline event
statuseventStringStatus available during penalty shootouts (period_type="penalties")

ex. missed, scored, not_taken_yet
stoppage_timeeventIntegerStoppage time value for a timeline event

ex. 3
stoppage_time_clockeventStringStoppage time clock value for a timeline event

ex. 2:03
typeeventStringType of timeline event. See our FAQ for a complete list of event types

ex. goal_kick, period_start, yellow_card
timeeventDate-timeTimestamp of a timeline event

ex. 2024-04-16T20:49:49+00:00
updatedeventBooleanSignifies this event has been updated since its original entry when true
updated_timeeventDate-timeTimestamp of an updated time entry

ex. 2024-04-22T17:17:24+00:00
xeventIntegerHorizontal 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.
yeventIntegerVertical 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
AttributeParent ElementTypeDescription
idevent - playersStringUnique player Id associated with a timeline event

ex. sr:player:2367105
nameevent - playersStringPlayer name associated with a timeline event

ex. Luna, Diego
typeevent - playersStringPlayer 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
AttributeParent ElementTypeDescription
aggregate_away_scoresport_event_statusIntegerAggregate score (of multiple sport events) for the away team
aggregate_home_scoresport_event_statusIntegerAggregate score (of multiple sport events) for the home team
aggregate_winner_idsport_event_statusStringUnique ID of the aggregate score winner

ex. sr:competitor:44
away_normaltime_scoresport_event_statusIntegerScore for the away team in normal time
away_overtime_scoresport_event_statusIntegerScore for the away team in overtime
away_scoresport_event_statusIntegerTotal score for the away team in the match
home_normaltime_scoresport_event_statusIntegerScore for the home team in normal time
home_overtime_scoresport_event_statusIntegerScore for the home team in overtime
home_scoresport_event_statusIntegerTotal score for the home team in the match
match_statussport_event_statusStringStatus 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_tiesport_event_statusBooleanSignifies a match ended in a tie when true
scout_abandonedsport_event_statusBooleanSignifies a match was abandoned by a scout when true
statussport_event_statusStringStatus of a match

ex. not_started, live, ended, awaiting_penalties

See our FAQ for a complete list of statuses and their definitions.
winner_idsport_event_statusStringUnique ID of the match winner

ex. sr:competitor:44
Ball Location

Visit our FAQ for additional information on ball location data.

AttributeParent ElementTypeDescription
ordersport_event_status - ball_locations - ball_locationIntegerSequential order of a ball location event. The most recent location is 4 and the oldest location is 1.
qualifiersport_event_status - ball_locations - ball_locationStringDesignation of a competitor for a ball location entry

home, away
xsport_event_status - ball_locations - ball_locationStringHorizontal X coordinate of the pitch. x is a number between 0 and 100. The reference point 0 is at the home team’s goal.
ysport_event_status - ball_locations - ball_locationStringVertical 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
AttributeParent ElementTypeDescription
playedsport_event_status - clockStringMatch clock time in minutes

90:00
stoppage_time_playedsport_event_status - clockStringStoppage time played in minutes

5:49
stoppage_time_announcedsport_event_status - clockStringStoppage time announced in minutes

5:00
statussport_event_status - match_situationStringCurrent situtation status of a match

safe, dangerous, attack
qualifiersport_event_status - match_situationStringDefines the team in the current situation status

home, away
updated_atsport_event_status - match_situationDate-TimeTimestamp of the most recent match situation update

ex. 2024-04-14T14:57:28+00:00
away_scoresport_event_status - period_scoresIntegerAway team period score
home_scoresport_event_status - period_scoresIntegerHome team period score
numbersport_event_status - period_scoresIntegerPeriod number
typesport_event_status - period_scoresStringPeriod type

regular_period, overtime, penalties, pause, awaiting_extra, extra_time_halftime, interrupted