Integration GuidesReference Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Reference Docs

Push Events

NBA Push Events retrieves detailed, real-time information on every game event.

Syntax

https://api.sportradar.com/nba/{access_level}/stream/{language_code}/events/subscribe

Parameters

ParameterDescription
access_levelDefines the access level of your API key

production, trial
language_codeOptional code for supported languages

en (English)
🔐

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 (&).

ParameterDescription
event_categoryEvent category

Example: event_category=shot
event_typeEvent type

Example: event_type=stoppage
localeLanguage returned expressed as a 2-letter code

en (English)

Example: locale=en
matchMatch id

Example: match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56
playersPlayer id

Example: players=sd:player:c1ff3e58-266f-4183-9fa1-d7c914cf4886
statusGame status

inprogress, created

Example: status=inprogress
teamTeam 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")

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/nba/trial/stream/en/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/nba/trial/stream/en/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/nba/trial/stream/en/events/subscribe?&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)
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/nba/trial/stream/en/events/subscribe",
    params = {'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 -X GET 'api.sportradar.com/nba/trial/stream/en/events/subscribe?&status=inprogress&match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56'
  -H 'x-api-key: {your_api_key}'


Response Sample

The above commands return json like this.


Simulations

Check out our Simulations to replay actual games at any time, on your own schedule. Push simulations are available as well.



Data Points

Game
AttributeParent ElementTypeDescription
coveragegameStringBirthplace of a prospect

Coverage level of a game

full, extended_boxscore
idgameGUIDUnique ID of a game

ex. 1f730a9a-8221-48ff-a259-ac2103fb58b0
referencegameStringLeague reference ID of a game

ex. 1610612758
sr_idgameGUIDUnique Sportradar ID of a game

ex. sr:match:35431817
statusgameStringThe 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
titlegameStringTitle of a game

ex. Game 3
scheduledgamedateTimeScheduled date and time of a game

ex. 2024-02-14T05:00:00Z
awaygame - time_zonesStringTime zone of the away team

ex. US/Pacific
homegame - time_zonesStringTime zone of the home team

ex. US/Eastern
venuegame - time_zonesStringTime zone of the venue

ex. US/Eastern
Metadata
AttributeParent ElementTypeDescription
event_categorymetadataStringCategory of an event

ex. lineupchange or shot
event_typemetadataStringType of an event

ex. threepointmiss or rebound
leaguemetadataStringAlias of a league

ex. NBA
localemetadataStringLanguage code

ex. en (English)
matchmetadataGUIDUnique ID of a game

ex. sd:match:d8539eb6-3e27-40c8-906f-9cd1736321d8
operationmetadataStringOperation of an update

update, delete
playersmetadataGUIDUnique ID(s) of players associated with an event

ex. sd:player:68b7aac9-02fd-4bd8-b10c-6702d2c5eb98,sd:player:ffa9a64f-d624-4033-bd23-59dcfd805175
statusmetadataStringThe 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
teammetadataGUIDUnique ID(s) of team(s) associated with an event

ex. sd:team:583ecefd-fb46-11e1-82cb-f4ce4684ea4c,sr:team:3410
versionmetadataStringVersion 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.

AttributeParent ElementTypeDescription
idevent - attributionGUIDUnique ID of a team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketevent - attributionStringMarket name of a team

ex. Sacramento
nameevent - attributionStringTeam name

ex. Kings
referenceevent - attributionStringLeague reference ID of a team

ex. 1610612750
sr_idevent - attributionGUIDUnique Sportradar ID of a team

ex. sr:team:3415
team_basketevent - attributionStringThe basket the offensive team is shooting at in the arena. Direction is based on the TV broadcast's perspective.

left, right
idevent - possessionGUIDUnique ID of a team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketevent - possessionStringMarket name of a team

ex. Sacramento
nameevent - possessionStringTeam name

ex. Kings
sr_idevent - possessionGUIDUnique Sportradar ID of a team

ex. sr:team:3415
Play-by-Play - Home/Away Teams
AttributeParent ElementTypeDescription
bonusgame - awayBooleanSignifies a team is in the bonus
pointsgame - awayIntegerTotal points for the away team
idgame - awayGUIDUnique ID of the away team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketgame - awayStringMarket name of the away team

ex. Sacramento
namegame - awayStringAway team name

ex. Kings
referencegame - awayStringLeague reference ID of the away team

ex. 1610612750
remaining_timeoutsgame - awayIntegerRemaining timeouts for the away team
sr_idgame - awayGUIDUnique Sportradar ID of the away team

ex. sr:team:3415
bonusgame - homeBooleanSignifies a team is in the bonus
pointsgame - homeIntegerTotal points for the home team
idgame - homeGUIDUnique ID of the home team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketgame - homeStringMarket name of the home team

ex. Sacramento
namegame - homeStringHome team name

ex. Kings
referencegame - homeStringLeague reference ID of the home team

ex. 1610612750
remaining_timeoutsgame - homeIntegerRemaining timeouts for the home team
sr_idgame - homeGUIDUnique Sportradar ID of the home team

ex. sr:team:3415
Play-by-Play - Event
AttributeParent ElementTypeDescription
clock_decimaleventStringClock value in decimal form when the game clock is under 1:00. Otherwise it displays the same value as clock

ex. 00:21.70
attempteventStringText description of a free throw attempt

ex. 1 of 2 or 2 of 2
away_pointseventIntegerTotal points for the away team after an event
clockeventStringClock value of an event

ex. 12:37
descriptioneventStringText description of an event

ex. Kevon Looney makes two point jump shot (Klay Thompson assists)
event_typeeventStringType of event

ex. turnover or rebound

*See our FAQ for a complete list of types
home_pointseventIntegerTotal points for the home team after an event
ideventGUIDUnique ID of an event

ex. b9feda23-c03f-4304-afa4-06d7dc830651
action_areaevent - locationStringAction 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_xevent - locationIntegerX coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
coord_yevent - locationIntegerY coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
numbereventIntegerSequential number of an event in a game
qualifierevent - qualifiers - qualifierStringAdditional 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
rescindedeventBooleanSignifies a technical foul event_type="technicalfoul") has been rescinded by the league when true
sequenceeventIntegerNIX timestamp of the wall clock value. Use this value to help sequence play-by-play events (smallest to largest sequence number).

ex. 1678835426293
turnover_typeeventStringType of turnover

ex. Traveling or Lane Violation

*See our FAQ for a complete list of types
createdeventdateTimeTimestamp of the creation of an event

ex. 2024-02-14T05:00:00Z
updatedeventdateTimeTimestamp of the last update to an event

ex. 2024-02-14T05:00:00Z
wall_clockeventdateTimeTimestamp in UTC when the on-venue statistician began entry of a play-by-play event.

ex. 2024-02-14T05:00:00Z
Play-by-Play - Play Participants & Stats
AttributeParent ElementTypeDescription
idevent - statistics - teamGUIDUnique ID of a team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketevent - statistics - teamStringMarket name of a team

ex. Sacramento
nameevent - statistics - teamStringTeam name

ex. Kings
referenceevent - statistics - teamStringLeague reference ID of a team

ex. 1610612750
sr_idevent - statistics - teamGUIDUnique Sportradar ID of a team

ex. sr:team:3415
full_nameevent - statistics - playerStringFull name of a player

ex. Stephen Curry
idevent - statistics - playerGUIDUnique player ID

ex. 8ec91366-faea-4196-bbfd-b8fab7434795
jersey_numberevent - statistics - playerIntegerNumber of a player's jersey
referenceevent - statistics - playerStringLeague reference ID of a player

ex. 1626157
sr_idevent - statistics - playerGUIDUnique Sportradar ID of a player

ex. sr:player:608110
madeevent - statisticsBooleanSignifies a made basket when true
pointsevent - statisticsIntegerNumber of points scored for an event
rebound_typeevent - statistics - reboundStringRebound type

defensive, offensive
shot_distanceevent - statisticsDecimalShot distance in feet from the basket

ex. 2.37
shot_typeevent - statisticsStringShot type

jump shot, layup, dunk, hook, tip
shot_type_descevent - statisticsStringText description of a shot type

ex. driving or alley-oop

*See our FAQ for a complete list of descriptions
three_point_shotevent - statisticsBooleanSignifies a 3-point attempt when true
madeevent - statistics - freethrowBooleanSignifies a made free throw when true
free_throw_typeevent - statistics - freethrowStringType of free throw

ex. regular, technical, flagrant, clear path
Play-by-Play - On Court Participants
AttributeParent ElementTypeDescription
full_nameevent - on_court - home / away - playersStringFull name of a player

ex. Stephen Curry
idevent - on_court - home / away - playersGUIDUnique player ID

ex. 8ec91366-faea-4196-bbfd-b8fab7434795
jersey_numberevent - on_court - home / away - playersIntegerNumber of a player's jersey
referenceevent - on_court - home / away - playersStringLeague reference ID of a player

ex. 1626157
sr_idevent - on_court - home / away - playersGUIDUnique Sportradar ID of a player

ex. sr:player:608110
idevent - on_court - home / awayGUIDUnique ID of a team

ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketevent - on_court - home / awayStringMarket name of a team

ex. Sacramento
nameevent - on_court - home / awayStringTeam name

ex. Kings
referenceevent - on_court - home / awayStringLeague reference ID of a team

ex. 1610612750
sr_idevent - on_court - home / awayGUIDUnique Sportradar ID of a team

ex. sr:team:3415
Quarter
AttributeParent ElementTypeDescription
idperiodGUIDUnique ID of a quarter

ex. fece1ac0-b703-4478-8a7c-3f27313dec97
numberperiodIntegerNumber of a quarter
sequenceperiodIntegerSequential number of a quarter
typeperiodGUIDType of period

ex. quarter