Integration GuidesReference Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Reference Docs

Play-by-Play

NBA Play-by-Play Detailed, real-time information on every team possession and game event.

⏱️

Update Frequency

TTL / Cache: This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress. Upon closed, it will transfer to 120s.

Data Updates: Realtime



Data Points

Season:
AttributeParent ElementTypeDescription
idgame - seasonGUIDUnique season ID
ex. 583eca2f-fb46-11e1-82cb-f4ce4684ea4c
namegame - seasonStringName of the season
ex. Post-season
typegame - seasonStringType of the season
PRE, REG, PIT, PST
yeargame - seasonIntegerYear of the season
Boxscore:
AttributeParent ElementTypeDescription
attendancegameIntegerAttendance of a game
ex. 19079
lead_changesgameIntegerNumber of lead changes in a game
times_tiedgameIntegerNumber of times tied in a game
lead_changesgame - quarter / overtime - scoringIntegerNumber of lead changes in a quarter
times_tiedgame - quarter / overtime - scoringIntegerNumber of times tied in a quarter
idovertimeGUIDUnique ID of overtime
ex. 1c2463d7-43ec-4b83-a29c-d66087d8e8df
numberovertimeIntegerOvertime number
sequenceovertimeIntegerPeriod sequence number (The first overtime sequence would be 5)
quartergameIntegerQuarter number of the game
idquarterGUIDUnique ID of a quarter
ex. 47091cc4-08c2-4f83-9d8d-59c3c85e1725
numberquarterIntegerQuarter number
Game:
AttributeParent ElementTypeDescription
aliasawayStringAbbreviation of the away team
ex. MEM (Memphis)
idawayGUIDUnique ID of the away team
ex. 583eca88-fb46-11e1-82cb-f4ce4684ea4c
away_teamgameGUIDUnique ID of the away team
ex. 583eca88-fb46-11e1-82cb-f4ce4684ea4c
nameawayStringTeam name of the away team
ex. Memphis Grizzlies
referenceawayStringLeague reference ID of the away team
ex. 1610612750
remaining_timeoutsawayIntegerRemaining timeouts for the away team
sr_idawayGUIDUnique Sportradar ID of the away team
ex. sr:team:3415
entry_modegameStringType of data entry for the game
WEBSOCKET (Connected to NBA's socket conneciton), HTTP (Connected to NBA's HTTP service), LDE (Live Data Entry by Sportradar)
clockgameStringClock value of the game
ex. 12:37
clock_decimalgameStringClock value in decimal form when the game clock is under 1:00. Otherwise it displays the same value as clock
ex. 00:21.70
coveragegameStringCoverage level of a game
full, extended_boxscore
durationgameStringDuration of a game
ex. 2:26
idgameGUIDUnique ID of a game
ex. 1f730a9a-8221-48ff-a259-ac2103fb58b0
inseason_tournamentgameBooleanSignifies a game is part of the In-Season Tournament
parent_idgameGUIDStandard parent ID of a game. Use this ID to group events (like the All-Star game) across seasons
ex. e4986bda-2f75-4228-8295-44b2449088b1
quartergameIntegerCurrent quarter of a game
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
aliashomeStringAbbreviation of the home team
ex. GSW (Golden State)
idhomeGUIDUnique ID of the home team
ex. 583ec825-fb46-11e1-82cb-f4ce4684ea4c
home_teamgameGUIDUnique ID of the home team
ex. 583ec825-fb46-11e1-82cb-f4ce4684ea4c
namehomeStringTeam name of the home team
ex. Golden State Warriors
referencehomeStringLeague reference ID of the home team
ex. 1610612750
remaining_timeoutshomeIntegerRemaining timeouts for the home team
sr_idhomeGUIDUnique Sportradar ID of the home team
ex. sr:team:3428
neutral_sitegameBooleanSignifies a game played at a neutral venue
scheduledgamedateTimeScheduled date and time of a game
ex. 2022-09-25T20:10:00+00:00
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
track_on_courtgameBooleanSignifies a game with tracking of players on the court.

When true, we provide a lineupchange event type, on_court player for Play-by-Play events, and an on_court indicator in Game Summary
Broadcast:
AttributeParent ElementTypeDescription
channelbroadcastStringName of a game's broadcast channel
ex. 649
localebroadcastStringSignifies the locale of a broadcast
ex. Home, Away, National
networkbroadcastStringName of a game's broadcast network
ex. ESPN
typebroadcastStringType of broadcast
ex. TV
Team Records:
AttributeParent ElementTypeDescription
lossesteam - recordIntegerNumber of team losses year-to-date before the game. Record is updated post-game based on the game outcome
winsteam - recordIntegerNumber of team wins year-to-date before the game. Record is updated post-game based on the game outcome
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
referenceevent - possessionStringLeague reference ID of a team
ex. 1610612750
sr_idevent - possessionGUIDUnique Sportradar ID of a team
ex. sr:team:3415
team_basketevent - possessionStringThe basket the offensive team is shooting at in the arena. Direction is based on the TV broadcast's perspective.
left, right
Play-by-Play - Home/Away Teams:
AttributeParent ElementTypeDescription
aliasscoring / quarter - awayStringAbbreviation of the away team
ex. MEM (Memphis)
bonusscoring / quarter - awayBooleanSignifies a team is in the bonus
pointsscoring - awayIntegerTotal points for the away team
pointsquarter - awayIntegerPoints in a quarter for the away team
idscoring / quarter - awayGUIDUnique ID of the away team
ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketscoring / quarter - awayStringMarket name of the away team
ex. Sacramento
namescoring / quarter - awayStringAway team name
ex. Kings
referencescoring / quarter - awayStringLeague reference ID of the away team
ex. 1610612750
sr_idscoring / quarter - awayGUIDUnique Sportradar ID of the away team
ex. sr:team:3415
aliasscoring / quarter - homeStringAbbreviation of the home team
ex. MEM (Memphis)
bonusscoring / quarter - homeBooleanSignifies a team is in the bonus
pointsscoring - homeIntegerTotal points for the home team
pointsquarter - homeIntegerPoints in a quarter for the home team
idscoring / quarter - homeGUIDUnique ID of the home team
ex. 583ed0ac-fb46-11e1-82cb-f4ce4684ea4c
marketscoring / quarter - homeStringMarket name of the home team
ex. Sacramento
namescoring / quarter - homeStringHome team name
ex. Kings
referencescoring / quarter - homeStringLeague reference ID of the home team
ex. 1610612750
sr_idscoring / quarter - 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
free_throw_typeeventStringType of free throw
ex. regular, technical, flagrant, clear path
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
qualifierevents - 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
sequenceeventIntegerUNIX 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. 2022-09-25T23:00:45+00:00
updatedeventdateTimeTimestamp of the last update to an event
ex. 2022-09-25T23:00:45+00:00
wall_clockeventdateTimeTimestamp 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:
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 - statistics - fieldgoalBooleanSignifies a made basket
pointsevent - statistics - fieldgoalIntegerNumber of points scored for an event
rebound_typeevent - statistics - reboundStringRebound type
defensive, offensive
shot_distanceevent - statistics - fieldgoalDecimalShot distance in feet from the basket
ex. 2.37
shot_typeevent - statistics - fieldgoalStringShot type
jump shot, layup, dunk, hook, tip
shot_type_descevent - statistics - fieldgoalStringText description of a shot type
ex. driving or alley-oop

See our FAQ for a complete list of descriptions
three_point_shotevent - statistics - fieldgoalBooleanSignifies a 3-point attempt
madeevent - statistics - freethrowBooleanSignifies a made free throw
pointsevent - statistics - freethrowIntegerNumber of points scored for a free throw
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 - playerStringFull name of a player
ex. Stephen Curry
idevent - on_court - playerGUIDUnique player ID
ex. 8ec91366-faea-4196-bbfd-b8fab7434795
jersey_numberevent - on_court - playerIntegerNumber of a player's jersey
referenceevent - on_court - playerStringLeague reference ID of a player
ex. 1626157
sr_idevent - on_court - playerGUIDUnique 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
Language
Authorization
Query
Click Try It! to start a request and see the response here!