Game Play-by-Play

Time	Status	User Agent
Retrieving recent requests…

⏱️
Update Frequency
TTL / Cache:

1 minute when a game is in scheduled status

2 seconds when a game moves to inprogress

10 minutes when a game moves to closed

4 hours when seven days have passed since closed

Data Updates: Realtime
Recommended Pull (Non-Live): As needed; the feed can be ignored until 10 minutes before the scheduled start, with the daily change log capturing post-game changes
Recommended Pull (Live): As fast as the response TTL allows while a game is live; begin requesting 10 minutes before the scheduled start

📘
Tracking Live Games
Learn how to use the Game Play-by-Play feed to capture every possession and game event in real time in our Live Game Updates integration scenario.

Data Points

Browse this endpoint's available data points and their definitions below.

Season

Attribute	Parent Element	Type	Description
`id`	`game` - `season`	GUID	Unique season ID ex. `2a29bf58-7069-4ca4-8933-0347544e243d`
`name`	`game` - `season`	String	Name of the season ex. `Post-season`
`type`	`game` - `season`	String	Type of the season `PRE`, `REG`, `SC`, `SCC`, `PST`, `EX`
`year`	`game` - `season`	Integer	Year of the season

Boxscore

Attribute	Parent Element	Type	Description
`attendance`	`game`	Integer	Attendance of a game ex. `19079`
`lead_changes`	`game`	Integer	Number of lead changes in a game
`times_tied`	`game`	Integer	Number of times tied in a game
`lead_changes`	`game` - `quarter` / `overtime` - `scoring`	Integer	Number of lead changes in a quarter
`times_tied`	`game` - `quarter` / `overtime` - `scoring`	Integer	Number of times tied in a quarter
`id`	`overtime`	GUID	Unique ID of overtime ex. `1c2463d7-43ec-4b83-a29c-d66087d8e8df`
`number`	`overtime`	Integer	Overtime number
`sequence`	`overtime`	Integer	Period sequence number (The first overtime sequence would be `5`)
`id`	`quarter`	GUID	Unique ID of a quarter ex. `47091cc4-08c2-4f83-9d8d-59c3c85e1725`
`number`	`quarter`	Integer	Quarter number

Game

Attribute	Parent Element	Type	Description
`away_team`	`game`	GUID	Unique ID of the away team ex. `583ec825-fb46-11e1-82cb-f4ce4684ea4c`
`home_team`	`game`	GUID	Unique ID of the home team ex. `583ec97e-fb46-11e1-82cb-f4ce4684ea4c`
`entry_mode`	`game`	String	Type of data entry for the game `WEBSOCKET` (Connected to NBA's socket connection), `HTTP` (Connected to NBA's HTTP service), `LDE` (Live Data Entry by Sportradar)
`clock`	`game`	String	Clock value of the game ex. `12:37`
`clock_decimal`	`game`	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`
`coverage`	`game`	String	Coverage level of a game `full`, `extended_boxscore`
`deleted`	`game`	Boolean	Signifies a game was deleted when `true`
`duration`	`game`	String	Duration of a game ex. `2:26`
`id`	`game`	GUID	Unique ID of a game ex. `1f730a9a-8221-48ff-a259-ac2103fb58b0`
`parent_id`	`game`	GUID	Standard parent ID of a game. Use this ID to group events across seasons ex. `e4986bda-2f75-4228-8295-44b2449088b1`
`quarter`	`game`	Integer	Current quarter of a game
`reference`	`game`	String	League reference ID of a game ex. `1610612758`
`status`	`game`	String	The status of a game `scheduled`, `created`, `inprogress`, `halftime`, `complete`, `closed`, `cancelled`, `delayed`, `postponed`, `time-tbd`, `if-necessary`, `unnecessary` See FAQ for details
`title`	`game`	String	Game title ex. `Game 6`
`track_on_court`	`game`	Boolean	Signifies 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
`neutral_site`	`game`	Boolean	Signifies a game played at a neutral venue
`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`

Broadcast

Attribute	Parent Element	Type	Description
`channel`	`broadcast`	String	Name of a game's broadcast channel ex. `216`
`locale`	`broadcast`	String	Signifies the locale of a broadcast ex. `Home`, `Away`, `National`
`network`	`broadcast`	String	Name of a game's broadcast network ex. `NBA TV`
`type`	`broadcast`	String	Type of broadcast ex. `TV` or `Internet`

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. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`event` - `attribution`	String	Market name of a team ex. `Delaware`
`name`	`event` - `attribution`	String	Team name ex. `Blue Coats`
`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. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`event` - `possession`	String	Market name of a team ex. `Delaware`
`name`	`event` - `possession`	String	Team name ex. `Blue Coats`
`team_basket`	`event` - `possession`	String	The 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

Attribute	Parent Element	Type	Description
`alias`	`scoring` / `quarter` - `away`	String	Abbreviation of the away team ex. `DEL` (Delaware)
`bonus`	`scoring` / `quarter` - `away`	Boolean	Signifies a team is in the bonus
`points`	`scoring` - `away`	Integer	Total points for the away team
`points`	`quarter` - `away`	Integer	Points in a quarter for the away team
`id`	`scoring` / `quarter` - `away`	GUID	Unique ID of the away team ex. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`scoring` / `quarter` - `away`	String	Market name of the away team ex. `Delaware`
`name`	`scoring` / `quarter` - `away`	String	Away team name ex. `Blue Coats`
`alias`	`scoring` / `quarter` - `home`	String	Abbreviation of the home team ex. `DEL` (Delaware)
`bonus`	`scoring` / `quarter` - `home`	Boolean	Signifies a team is in the bonus
`points`	`scoring` - `home`	Integer	Total points for the home team
`points`	`quarter` - `home`	Integer	Points in a quarter for the home team
`id`	`scoring` / `quarter` - `home`	GUID	Unique ID of the home team ex. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`scoring` / `quarter` - `home`	String	Market name of the home team ex. `Delaware`
`name`	`scoring` / `quarter` - `home`	String	Home team name ex. `Blue Coats`

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. `Norense Odiase blocks Jaden Springer's two point driving dunk`
`event_type`	`event`	String	Type of event ex. `turnover` or `rebound` See our FAQ for a complete list of types
`free_throw_type`	`event`	String	Type of free throw ex. `regular`, `technical`, `flagrant`, `clear path`
`home_points`	`event`	Integer	Total points for the home team after an event
`id`	`event`	GUID	Unique ID of an event ex. `c90dfffe-51f5-4e62-aeda-c4332cf3bd91`
`action_area`	`event` - `location`	String	Action area of an event `underbasket`, `inthepaint`, `insiderightwing`, `insideright`, `insidecenter`, `insideleft`, `insideleftwing`, `outsideright`, `outsidecenter`, `outsideleft`, `outsideleftwing`, `backcourt` See our FAQ for detailed plot points
`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`, `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. `2022-09-25T23:00:45+00:00`
`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. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`event` - `statistics` - `team`	String	Market name of a team ex. `Delaware`
`name`	`event` - `statistics` - `team`	String	Team name ex. `Blue Coats`
`full_name`	`event` - `statistics` - `player`	String	Full name of a player ex. `Mac McClung`
`id`	`event` - `statistics` - `player`	GUID	Unique player ID ex. `0ef9d4c8-866d-49fe-9752-d36947794876`
`jersey_number`	`event` - `statistics` - `player`	String	Number of a player's jersey
`made`	`event` - `statistics` - `fieldgoal`	Boolean	Signifies a made basket
`points`	`event` - `statistics` - `fieldgoal`	Integer	Number of points scored for an event
`rebound_type`	`event` - `statistics` - `rebound`	String	Rebound type `defensive`, `offensive`
`shot_distance`	`event` - `statistics` - `fieldgoal`	Decimal	Shot distance in feet from the basket ex. `2.37`
`shot_type`	`event` - `statistics` - `fieldgoal`	String	Shot type `jump shot`, `layup`, `dunk`, `hook`, `tip`
`shot_type_desc`	`event` - `statistics` - `fieldgoal`	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` - `fieldgoal`	Boolean	Signifies a 3-point attempt
`made`	`event` - `statistics` - `freethrow`	Boolean	Signifies a made free throw
`points`	`event` - `statistics` - `freethrow`	Integer	Number of points scored for a 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` - `player`	String	Full name of a player ex. `Mac McClung`
`id`	`event` - `on_court` - `player`	GUID	Unique player ID ex. `a7ad124e-7060-402d-8ad3-a982af52eb93`
`jersey_number`	`event` - `on_court` - `player`	String	Number of a player's jersey
`id`	`event` - `on_court` - `home` / `away`	GUID	Unique ID of a team ex. `67a79348-041a-45f6-bb12-722d38dc8dbf`
`market`	`event` - `on_court` - `home` / `away`	String	Market name of a team ex. `Delaware`
`name`	`event` - `on_court` - `home` / `away`	String	Team name ex. `Blue Coats`

Update Frequency

Tracking Live Games

Data Points

200200