Push Events

Syntax

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

Replace the placeholders with the following path parameters:

Parameter	Description
`access_level`	Defines the access level of your API key as Production (`production`), Trial (`trial`), or Simulation (`simulation`).
`language_code`	Optional code for supported languages: `en` (English) or translations (Any other language translations. See optional query string parameters for locale.)
`your_api_key`	Your API key.

Optional Query String Parameters

In addition to the URL parameters listed above, you can filter the event information with one or more of the following optional query string parameters.

📘
Note
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.

Replace placeholders with the following query parameters:

Parameter	Description
`event_category`	Event category expressed as: {event_category}. Example: `event_category=shot`
`event_type`	Event type expressed as: {event_type}. Example: `event_type=stoppage`
`locale`	Locale expressed as 2 letter code: locale={language_code} Example: `locale=en`
`match`	Match id expressed as: sd:match:{match_id}. Example: `match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56`
`players`	Player id expressed as: sd:player:{player_id}. Example: `players=sd:player:c1ff3e58-266f-4183-9fa1-d7c914cf4886`
`status`	Status type expressed as: inprogress or created. Example: `status=inprogress`
`team`	Team id expressed as: sd:team:{team_id}. Example: `team=sd:team:583eca2f-fb46-11e1-82cb-f4ce4684ea4c`

Code Samples

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

url = URI("https://api.sportradar.com/nba/trial/stream/en/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/nba/trial/stream/en/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.us/nba/trial/stream/en/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/nba/trial/stream/en/events/subscribe?api_key={your_api_key}&status=inprogress&match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56")

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/nba/trial/stream/en/events/subscribe",
    params = {'api_key': 'your_api_key', 'status': 'inprogress', 'match': 'sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56'},
    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.us/nba/trial/stream/en/events/subscribe?api_key={your_api_key}&status=inprogress&match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56'

Response Sample

The above commands return json like this.

Data Points

Game:

Attribute	Parent Element	Type	Description
`coverage`	`game`	String	Coverage level of a game `full`, `extended_boxscore`
`id`	`game`	GUID	Unique ID of a game ex. `1f730a9a-8221-48ff-a259-ac2103fb58b0`
`reference`	`game`	String	League reference ID of a game ex. `1610612758`
`sr_id`	`game`	GUID	Unique Sportradar ID of a game ex. `sr:match:35431817`
`status`	`game`	String	The status of a game `scheduled`, `created`, `inprogress`, `halftime`, `complete`, `closed`, `cancelled`, `delayed`, `postponed`, `time-tbd`, `if-necessary`, `unnecessary` Please see our FAQ section for a list of game status definitions
`title`	`game`	String	Title of a game ex. `Game 3`
`scheduled`	`game`	dateTime	Scheduled date and time of a game ex. `2022-09-25T20:10:00+00:00`
`away`	`game` - `time_zones`	String	Time zone of the away team ex. `US/Pacific`
`home`	`game` - `time_zones`	String	Time zone of the home team ex. `US/Eastern`
`venue`	`game` - `time_zones`	String	Time zone of the venue ex. `US/Eastern`

Metadata:

Attribute	Parent Element	Type	Description
`event_category`	`metadata`	String	Category of an event ex. `lineupchange` or `shot`
`event_type`	`metadata`	String	Type of an event ex. `threepointmiss` or `rebound`
`league`	`metadata`	String	Alias of a league ex. `NBA`
`locale`	`metadata`	String	Language code ex. `en` (English)
`match`	`metadata`	GUID	Unique ID of a game ex. `sd:match:d8539eb6-3e27-40c8-906f-9cd1736321d8`
`operation`	`metadata`	String	Operation of an update `update`, `delete`
`players`	`metadata`	GUID	Unique ID(s) of players associated with an event ex. `sd:player:68b7aac9-02fd-4bd8-b10c-6702d2c5eb98,sd:player:ffa9a64f-d624-4033-bd23-59dcfd805175`
`status`	`metadata`	String	The status of a game `scheduled`, `created`, `inprogress`, `halftime`, `complete`, `closed`, `cancelled`, `delayed`, `postponed`, `time-tbd`, `if-necessary`, `unnecessary` Please see our FAQ section for a list of game status definitions
`team`	`metadata`	GUID	Unique ID(s) of team(s) associated with an event ex. `sd:team:583ecefd-fb46-11e1-82cb-f4ce4684ea4c,sr:team:3410`
`version`	`metadata`	String	Version of the API ex. `v7`

Play-by-Play - Attribution & Possession:

Attribution is the team associated with the play-by-play event (i.e. the statistic associated with it). Possession is the team who currently has the possession of the ball as a result of that play-by-play event.

Attribute	Parent Element	Type	Description
`id`	`event` - `attribution`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `attribution`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `attribution`	String	Team name ex. `Kings`
`reference`	`event` - `attribution`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `attribution`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`
`team_basket`	`event` - `attribution`	String	The basket the offensive team is shooting at in the arena. Direction is based on the TV broadcast's perspective. `left`, `right`
`id`	`event` - `possession`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `possession`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `possession`	String	Team name ex. `Kings`
`sr_id`	`event` - `possession`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`

Play-by-Play - Home/Away Teams:

Attribute	Parent Element	Type	Description
`bonus`	`game` - `away`	Boolean	Signifies a team is in the bonus
`points`	`game` - `away`	Integer	Total points for the away team
`id`	`game` - `away`	GUID	Unique ID of the away team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`game` - `away`	String	Market name of the away team ex. `Sacramento`
`name`	`game` - `away`	String	Away team name ex. `Kings`
`reference`	`game` - `away`	String	League reference ID of the away team ex. `1610612750`
`remaining_timeouts`	`game` - `away`	Integer	Remaining timeouts for the away team
`sr_id`	`game` - `away`	GUID	Unique Sportradar ID of the away team ex. `sr:team:3415`
`bonus`	`game` - `home`	Boolean	Signifies a team is in the bonus
`points`	`game` - `home`	Integer	Total points for the home team
`id`	`game` - `home`	GUID	Unique ID of the home team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`game` - `home`	String	Market name of the home team ex. `Sacramento`
`name`	`game` - `home`	String	Home team name ex. `Kings`
`reference`	`game` - `home`	String	League reference ID of the home team ex. `1610612750`
`remaining_timeouts`	`game` - `home`	Integer	Remaining timeouts for the home team
`sr_id`	`game` - `home`	GUID	Unique Sportradar ID of the home team ex. `sr:team:3415`

Play-by-Play - Event:

Attribute	Parent Element	Type	Description
`clock_decimal`	`event`	String	Clock value in decimal form when the game clock is under 1:00. Otherwise it displays the same value as `clock` ex. `00:21.70`
`created`	`event`	dateTime	Timestamp of the creation of an event ex. `2022-09-25T23:00:45+00:00`
`attempt`	`event`	String	Text description of a free throw attempt ex. `1 of 2` or `2 of 2`
`away_points`	`event`	Integer	Total points for the away team after an event
`clock`	`event`	String	Clock value of an event ex. `12:37`
`description`	`event`	String	Text description of an event ex. `Kevon Looney makes two point jump shot (Klay Thompson assists)`
`event_type`	`event`	String	Type of event ex. `turnover` or `rebound` See our FAQ for a complete list of types
`home_points`	`event`	Integer	Total points for the home team after an event
`id`	`event`	GUID	Unique ID of an event ex. `b9feda23-c03f-4304-afa4-06d7dc830651`
`action_area`	`event` - `location`	String	Action area of an event `underbasket`, `inthepaint`, `insiderightwing`, `insideright`, `insidecenter`, `insideleft`, `insideleftwing`, `outsideright`, `outsidecenter`, `outsideleft`, `outsideleftwing`, `backcourt` Please see our FAQ for detailed plot points of our action areas
`coord_x`	`event` - `location`	Integer	X coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
`coord_y`	`event` - `location`	Integer	Y coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
`number`	`event`	Integer	Sequential number of an event in a game
`qualifier`	`events` - `qualifiers` - `qualifier`	String	Additional descriptor of a play-by-play event type. Appears only in JSON format `2ndchance`, `fastbreak`, `fromturnover`, `defensivegoaltending`, `pointsinthepaint`, `fastbreak`, `fromturnover`, `team`, `deadball`, `1freethrow`.`2freethrow`, `mandatory`
`rescinded`	`event`	Boolean	Signifies a technical foul `event_type="technicalfoul"`) has been rescinded by the league when `true`
`sequence`	`event`	Integer	UNIX timestamp of the wall clock value. Use this value to help sequence play-by-play events (smallest to largest sequence number}. ex. `1678835426293`
`turnover_type`	`event`	String	Type of turnover ex. `Traveling` or `Lane Violation` See our FAQ for a complete list of types
`updated`	`event`	dateTime	Timestamp of the last update to an event ex. `2022-09-25T23:00:45+00:00`
`wall_clock`	`event`	dateTime	Timestamp in UTC when the on-venue statistician began entry of a play-by-play event. ex. `2023-03-14T23:10:26Z`

Play-by-Play - Play Participants & Stats:

Attribute	Parent Element	Type	Description
`id`	`event` - `statistics` - `team`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `statistics` - `team`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `statistics` - `team`	String	Team name ex. `Kings`
`reference`	`event` - `statistics` - `team`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `statistics` - `team`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`
`full_name`	`event` - `statistics` - `player`	String	Full name of a player ex. `Stephen Curry`
`id`	`event` - `statistics` - `player`	GUID	Unique player ID ex. `8ec91366-faea-4196-bbfd-b8fab7434795`
`jersey_number`	`event` - `statistics` - `player`	Integer	Number of a player's jersey
`reference`	`event` - `statistics` - `player`	String	League reference ID of a player ex. `1626157`
`sr_id`	`event` - `statistics` - `player`	GUID	Unique Sportradar ID of a player ex. `sr:player:608110`
`made`	`event` - `statistics`	Boolean	Signifies a made basket
`points`	`event` - `statistics`	Integer	Number of points scored for an event
`rebound_type`	`event` - `statistics` - `rebound`	String	Rebound type `defensive`, `offensive`
`shot_distance`	`event` - `statistics`	Decimal	Shot distance in feet from the basket ex. `2.37`
`shot_type`	`event` - `statistics`	String	Shot type `jump shot`, `layup`, `dunk`, `hook`, `tip`
`shot_type_desc`	`event` - `statistics`	String	Text description of a shot type ex. `driving` or `alley-oop` See our FAQ for a complete list of descriptions
`three_point_shot`	`event` - `statistics`	Boolean	Signifies a 3-point attempt
`made`	`event` - `statistics` - `freethrow`	Boolean	Signifies a made free throw
`free_throw_type`	`event` - `statistics` - `freethrow`	String	Type of free throw ex. `regular`, `technical`, `flagrant`, `clear path`

Play-by-Play - On Court Participants:

Attribute	Parent Element	Type	Description
`full_name`	`event` - `on_court` - `home` / `away` - `players`	String	Full name of a player ex. `Stephen Curry`
`id`	`event` - `on_court` - `home` / `away` - `players`	GUID	Unique player ID ex. `8ec91366-faea-4196-bbfd-b8fab7434795`
`jersey_number`	`event` - `on_court` - `home` / `away` - `players`	Integer	Number of a player's jersey
`reference`	`event` - `on_court` - `home` / `away` - `players`	String	League reference ID of a player ex. `1626157`
`sr_id`	`event` - `on_court` - `home` / `away` - `players`	GUID	Unique Sportradar ID of a player ex. `sr:player:608110`
`id`	`event` - `on_court` - `home` / `away`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `on_court` - `home` / `away`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `on_court` - `home` / `away`	String	Team name ex. `Kings`
`reference`	`event` - `on_court` - `home` / `away`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `on_court` - `home` / `away`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`

Quarter:

Attribute	Parent Element	Type	Description
`id`	`period`	GUID	Unique ID of a quarter ex. `fece1ac0-b703-4478-8a7c-3f27313dec97`
`number`	`period`	Integer	Number of a quarter
`sequence`	`period`	Integer	Sequential number of a quarter
`type`	`period`	GUID	Type of period ex. `quarter`

Syntax

Optional Query String Parameters

📘Note

Code Samples

Samples with Query String Params

Response Sample

Data Points

📘
Note