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

Parameter

Description

access_level

Defines the access level of your API key

production, trial

language_code

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

Parameter

Description

event_category

Event category

Example: event_category=shot

event_type

Event type

Example: event_type=stoppage

locale

Language returned expressed as a 2-letter code

en (English)

Example: locale=en

match

Match id

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

players

Player id

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

status

Game status

inprogress, created

Example: status=inprogress

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")

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:

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. 2024-02-14T05:00:00Z

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.

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:

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

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

created

event

dateTime

Timestamp of the creation of an event
ex. 2024-02-14T05:00:00Z

updated

event

dateTime

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

wall_clock

event

dateTime

Timestamp 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:

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:
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