Skip to contents

Get NBA Stats API Play-by-Play V3

Get NBA Stats API Play-by-Play V3

Get NBA Stats API play-by-play

Get NBA Stats API play-by-play

Get NBA Stats API play-by-play (Multiple Games)

Get NBA Stats API play-by-play (Multiple Games)

Get NBA Stats API Live play-by-play

Get NBA Stats API Live play-by-play

Get NBA Stats API Live Boxscore

Get NBA Stats API Live Boxscore

Usage

nba_playbyplayv3(game_id, start_period = 0, end_period = 0, ...)

nba_pbp(game_id, on_court = TRUE, version = "v3", p = NULL, ...)

nba_pbps(
  game_ids = NULL,
  on_court = TRUE,
  version = "v3",
  nest_data = FALSE,
  ...
)

nba_live_pbp(game_id, ...)

nba_live_boxscore(game_id, ...)

Arguments

game_id

Game ID

start_period

Start period filter (default: 0 = all periods). Use 1-4 for regulation quarters, 5+ for overtime.

end_period

End period filter (default: 0 = all periods). Use 1-4 for regulation quarters, 5+ for overtime.

...

Additional arguments passed to an underlying function like httr.

on_court

If TRUE (default), on-court player IDs are added for each play event. V3 uses nba_gamerotation() stint data; V2 infers lineups from substitution events.

version

Play-by-play version - "v3" (default) or "v2". V3 returns richer data with shot coordinates, shot values, and V3 action types. Both versions reach back to 1996-97 (playbyplayv2 and playbyplayv3 share the stats.nba.com floor); the 2016-17 floor belongs to the data.nba.com / cdn.nba.com liveData feed served by nba_data_pbp().

p

Optional progress object from progressr (default: NULL). Used internally by nba_pbps().

game_ids

Game IDs

nest_data

If TRUE returns nested data by game

Value

A named list of hoopR_data tibbles: PlayByPlay, AvailableVideo.

PlayByPlay

col_nametypesdescription
game_idcharacterUnique game identifier.
action_numberintegerSequential action number within a game (V3 PBP).
clockcharacterGame clock value.
periodintegerPeriod of the game (1-4 quarters; 5+ for OT).
team_idintegerUnique team identifier.
team_tricodecharacterThree-letter team code (e.g. 'LAS' / 'NYL').
person_idintegerUnique player identifier (V3 endpoints).
player_namecharacterPlayer name.
player_name_icharacterPlayer name i.
x_legacyintegerV2-format X coordinate (preserved for V3-to-V2 compatibility).
y_legacyintegerV2-format Y coordinate (preserved for V3-to-V2 compatibility).
shot_distancenumericShot distance from the basket, in feet.
shot_resultcharacterShot result ('Made' / 'Missed').
is_field_goalinteger1 if the action was a field goal; 0 otherwise.
score_homecharacterScore home.
score_awaycharacterScore away.
points_totalintegerRunning total of points scored.
locationcharacterLocation.
descriptioncharacterLong-form description text.
action_typecharacterAction type label (e.g. 'Made Shot', 'Substitution').
sub_typecharacterAction sub-type label.
video_availableintegerVideo available.
shot_valueintegerPoint value of the shot (2 or 3).
action_idintegerUnique action identifier within a game (V3 PBP).

AvailableVideo

col_nametypesdescription
video_availableintegerVideo available.

A hoopR_data tibble with one row per play-by-play event.

col_nametypesdescription
game_idcharacterUnique game identifier.
event_numcharacterSequential event number within the game (V2 PBP).
event_typecharacterEvent / play type code (V2 PBP).
event_action_typecharacterNumeric event-action-type code (V2 PBP).
periodnumericPeriod of the game (1-4 quarters; 5+ for OT).
clockcharacterGame clock value.
minute_gamenumericMinute game.
time_remainingnumericTime remaining.
wc_time_stringcharacterWc time string.
time_quartercharacterTime quarter.
minute_remaining_quarternumericMinute remaining quarter.
seconds_remaining_quarternumericSeconds remaining quarter.
action_typecharacterAction type label (e.g. 'Made Shot', 'Substitution').
sub_typecharacterAction sub-type label.
home_descriptioncharacterHome team's description.
neutral_descriptioncharacterNeutral description.
visitor_descriptioncharacterVisitor description.
descriptioncharacterLong-form description text.
locationcharacterLocation.
scorecharacterFinal score.
away_scorenumericAway team score at the time of the play.
home_scorenumericHome team score at the time of the play.
score_margincharacterScore margin.
person1typecharacterPerson1type.
player1_idcharacterV2 PBP primary player ID (e.g. shooter / fouler).
player1_namecharacterV2 PBP primary player name.
player1_team_idcharacterTeam ID of player1.
player1_team_citycharacterPlayer1 team city.
player1_team_nicknamecharacterPlayer1 team nickname.
player1_team_abbreviationcharacterPlayer1 team abbreviation.
person2typecharacterPerson2type.
player2_idcharacterV2 PBP secondary player ID (e.g. assister / fouled-by).
player2_namecharacterV2 PBP secondary player name.
player2_team_idcharacterTeam ID of player2.
player2_team_citycharacterPlayer2 team city.
player2_team_nicknamecharacterPlayer2 team nickname.
player2_team_abbreviationcharacterPlayer2 team abbreviation.
person3typecharacterPerson3type.
player3_idcharacterV2 PBP tertiary player ID (e.g. blocker).
player3_namecharacterV2 PBP tertiary player name.
player3_team_idcharacterTeam ID of player3.
player3_team_citycharacterPlayer3 team city.
player3_team_nicknamecharacterPlayer3 team nickname.
player3_team_abbreviationcharacterPlayer3 team abbreviation.
video_available_flagcharacterVideo available flag.
team_leadingcharacterTeam leading.
x_legacyintegerV2-format X coordinate (preserved for V3-to-V2 compatibility).
y_legacyintegerV2-format Y coordinate (preserved for V3-to-V2 compatibility).
shot_distancenumericShot distance from the basket, in feet.
shot_resultcharacterShot result ('Made' / 'Missed').
is_field_goalinteger1 if the action was a field goal; 0 otherwise.
points_totalintegerRunning total of points scored.
shot_valueintegerPoint value of the shot (2 or 3).
away_player1numericAway team's player1.
away_player2numericAway team's player2.
away_player3numericAway team's player3.
away_player4numericAway team's player4.
away_player5numericAway team's player5.
home_player1numericHome team's player1.
home_player2numericHome team's player2.
home_player3numericHome team's player3.
home_player4numericHome team's player4.
home_player5numericHome team's player5.

A tibble with one row per play-by-play event.

col_nametypesdescription
game_idcharacterUnique game identifier.
event_numcharacterSequential event number within the game (V2 PBP).
event_typecharacterEvent / play type code (V2 PBP).
event_action_typecharacterNumeric event-action-type code (V2 PBP).
periodnumericPeriod of the game (1-4 quarters; 5+ for OT).
clockcharacterGame clock value.
minute_gamenumericMinute game.
time_remainingnumericTime remaining.
wc_time_stringcharacterWc time string.
time_quartercharacterTime quarter.
minute_remaining_quarternumericMinute remaining quarter.
seconds_remaining_quarternumericSeconds remaining quarter.
action_typecharacterAction type label (e.g. 'Made Shot', 'Substitution').
sub_typecharacterAction sub-type label.
home_descriptioncharacterHome team's description.
neutral_descriptioncharacterNeutral description.
visitor_descriptioncharacterVisitor description.
descriptioncharacterLong-form description text.
locationcharacterLocation.
scorecharacterFinal score.
away_scorenumericAway team score at the time of the play.
home_scorenumericHome team score at the time of the play.
score_margincharacterScore margin.
person1typecharacterPerson1type.
player1_idcharacterV2 PBP primary player ID (e.g. shooter / fouler).
player1_namecharacterV2 PBP primary player name.
player1_team_idcharacterTeam ID of player1.
player1_team_citycharacterPlayer1 team city.
player1_team_nicknamecharacterPlayer1 team nickname.
player1_team_abbreviationcharacterPlayer1 team abbreviation.
person2typecharacterPerson2type.
player2_idcharacterV2 PBP secondary player ID (e.g. assister / fouled-by).
player2_namecharacterV2 PBP secondary player name.
player2_team_idcharacterTeam ID of player2.
player2_team_citycharacterPlayer2 team city.
player2_team_nicknamecharacterPlayer2 team nickname.
player2_team_abbreviationcharacterPlayer2 team abbreviation.
person3typecharacterPerson3type.
player3_idcharacterV2 PBP tertiary player ID (e.g. blocker).
player3_namecharacterV2 PBP tertiary player name.
player3_team_idcharacterTeam ID of player3.
player3_team_citycharacterPlayer3 team city.
player3_team_nicknamecharacterPlayer3 team nickname.
player3_team_abbreviationcharacterPlayer3 team abbreviation.
video_available_flagcharacterVideo available flag.
team_leadingcharacterTeam leading.
x_legacyintegerV2-format X coordinate (preserved for V3-to-V2 compatibility).
y_legacyintegerV2-format Y coordinate (preserved for V3-to-V2 compatibility).
shot_distancenumericShot distance from the basket, in feet.
shot_resultcharacterShot result ('Made' / 'Missed').
is_field_goalinteger1 if the action was a field goal; 0 otherwise.
points_totalintegerRunning total of points scored.
shot_valueintegerPoint value of the shot (2 or 3).
away_player1numericAway team's player1.
away_player2numericAway team's player2.
away_player3numericAway team's player3.
away_player4numericAway team's player4.
away_player5numericAway team's player5.
home_player1numericHome team's player1.
home_player2numericHome team's player2.
home_player3numericHome team's player3.
home_player4numericHome team's player4.
home_player5numericHome team's player5.

A hoopR_data tibble with one row per play-by-play event.

col_nametypesdescription
event_numintegerSequential event number within the game (V2 PBP).
clockcharacterGame clock value.
time_actualcharacterTime actual.
periodintegerPeriod of the game (1-4 quarters; 5+ for OT).
period_typecharacterPeriod type.
action_typecharacterAction type label (e.g. 'Made Shot', 'Substitution').
sub_typecharacterAction sub-type label.
qualifierslistQualifiers.
player1_idintegerV2 PBP primary player ID (e.g. shooter / fouler).
xnumericX.
ynumericY.
offense_team_idintegerUnique identifier for offense team.
home_scorecharacterHome team score at the time of the play.
away_scorecharacterAway team score at the time of the play.
editedcharacterEdited.
orderintegerDisplay order within the result set.
is_target_score_last_periodlogicalIs target score last period.
x_legacyintegerV2-format X coordinate (preserved for V3-to-V2 compatibility).
y_legacyintegerV2-format Y coordinate (preserved for V3-to-V2 compatibility).
is_field_goalinteger1 if the action was a field goal; 0 otherwise.
sidecharacterSide label (e.g. 'home', 'away', or 'overUnder').
descriptioncharacterLong-form description text.
person_ids_filterlistPerson ids filter.
team_idintegerUnique team identifier.
team_tricodecharacterThree-letter team code (e.g. 'LAS' / 'NYL').
descriptorcharacterDescriptor.
jump_ball_recovered_namecharacterJump ball recovered name.
jump_ball_recoverd_person_idintegerUnique identifier for jump ball recoverd person.
player_namecharacterPlayer name.
player_name_icharacterPlayer name i.
jump_ball_won_player_namecharacterJump ball won player name.
jump_ball_won_person_idintegerUnique identifier for jump ball won person.
jump_ball_lost_player_namecharacterJump ball lost player name.
jump_ball_lost_person_idintegerUnique identifier for jump ball lost person.
areacharacterArea.
area_detailcharacterArea detail.
shot_distancenumericShot distance from the basket, in feet.
shot_resultcharacterShot result ('Made' / 'Missed').
points_totalintegerRunning total of points scored.
assist_player_name_initialcharacterAssist player name initial.
assist_person_idintegerUnique identifier for assist person.
assist_totalintegerAssist total.
shot_action_numberintegerShot action number.
rebound_totalintegerRebound total.
rebound_defensive_totalintegerRebound defensive total.
rebound_offensive_totalintegerRebound offensive total.
official_idintegerUnique official / referee identifier.
foul_personal_totalintegerFoul personal total.
foul_technical_totalintegerFoul technical total.
foul_drawn_player_namecharacterFoul drawn player name.
foul_drawn_person_idintegerUnique identifier for foul drawn person.
block_player_namecharacterBlock player name.
block_person_idintegerUnique identifier for block person.
turnover_totalintegerTurnover total.
steal_player_namecharacterSteal player name.
steal_person_idintegerUnique identifier for steal person.
player2_idintegerV2 PBP secondary player ID (e.g. assister / fouled-by).
player3_idintegerV2 PBP tertiary player ID (e.g. blocker).

A named list of hoopR_data tibbles: game_details, arena, officials, home_team_boxscore, away_team_boxscore, home_team_player_boxscore, away_team_player_boxscore, home_team_linescores, away_team_linescores.

game_details

col_nametypesdescription
game_idcharacterUnique game identifier.
game_time_localcharacterGame time local.
game_time_utccharacterGame start time in UTC (ISO 8601 timestamp).
game_time_homecharacterGame time home.
game_time_awaycharacterGame time away.
game_etcharacterGame et.
durationintegerDuration.
game_codecharacterESPN game code (numeric identifier).
game_status_textcharacterGame status display text (e.g. 'Final', '4:32 - 4th').
game_statusintegerGame status label.
regulation_periodsintegerRegulation periods.
periodintegerPeriod of the game (1-4 quarters; 5+ for OT).
game_clockcharacterGame clock.
attendanceintegerReported attendance.
selloutcharacterSellout.
home_team_idintegerUnique identifier for the home team.
home_team_namecharacterHome team name.
home_team_citycharacterHome team city / location.
home_team_tricodecharacterHome team three-letter code.
home_team_scoreintegerHome team's score.
home_team_in_bonuscharacterHome team's team in bonus.
home_team_timeouts_remainingintegerHome team's team timeouts remaining.
away_team_idintegerUnique identifier for the away team.
away_team_namecharacterAway team name.
away_team_citycharacterAway team city / location.
away_team_tricodecharacterAway team three-letter code.
away_team_scoreintegerAway team's score.
away_team_in_bonuscharacterAway team's team in bonus.
away_team_timeouts_remainingintegerAway team's team timeouts remaining.

arena

col_nametypesdescription
arena_idintegerUnique identifier for arena.
arena_namecharacterArena name.
arena_citycharacterArena city.
arena_statecharacterArena state.
arena_countrycharacterArena country.
arena_timezonecharacterArena timezone.

officials

col_nametypesdescription
person_idintegerUnique player identifier (V3 endpoints).
namecharacterDisplay name.
name_icharacterInitialed name (e.g. 'A. Wilson').
first_namecharacterPlayer's first name.
family_namecharacterPlayer's family / last name.
jersey_numcharacterJersey number worn by the player.
assignmentcharacterAssignment.

home_team_boxscore

col_nametypesdescription
team_idintegerUnique team identifier.
team_namecharacterFull team display name (e.g. 'Las Vegas Aces').
team_citycharacterTeam city or region (e.g. 'Las Vegas').
team_tricodecharacterThree-letter team code (e.g. 'LAS' / 'NYL').
team_scoreintegerTeam's score / final score.
team_in_bonuscharacterTeam in bonus.
team_timeouts_remainingintegerTeam timeouts remaining.
assistsintegerTotal assists.
assists_turnover_rationumericAssists turnover ratio.
bench_pointsintegerPoints scored by the bench.
biggest_leadintegerBiggest lead.
biggest_lead_scorecharacterBiggest lead score.
biggest_scoring_runintegerBiggest scoring run.
biggest_scoring_run_scorecharacterBiggest scoring run score.
blocksintegerTotal blocks.
blocks_receivedintegerShots blocked by opponents while attempting.
fast_break_points_attemptedintegerNumber of fast break points attempted.
fast_break_points_madeintegerNumber of fast break points made.
fast_break_points_percentagenumericFast break points percentage (0-1 decimal).
field_goals_attemptedintegerField goal attempts (2-pt + 3-pt).
field_goals_effective_adjustednumericField goals effective adjusted.
field_goals_madeintegerField goals made (2-pt + 3-pt).
field_goals_percentagenumericField goal percentage (0-1 decimal).
fouls_offensiveintegerOffensive fouls.
fouls_drawnintegerPersonal fouls drawn (by opponent's actions).
fouls_personalintegerPersonal fouls.
fouls_teamintegerFouls team.
fouls_technicalintegerTechnical fouls.
fouls_team_technicalintegerFouls team technical.
free_throws_attemptedintegerFree throw attempts.
free_throws_madeintegerFree throws made.
free_throws_percentagenumericFree throw percentage (0-1 decimal).
lead_changesintegerLead changes.
minutescharacterMinutes played, formatted MM:SS (V3 PT-duration parsed) or decimal minutes (V2).
minutes_calculatedcharacterMinutes calculated from game-clock differences.
pointsintegerPoints scored.
points_againstintegerPoints allowed.
points_fast_breakintegerFast-break points scored.
points_from_turnoversintegerPoints from turnovers.
points_in_the_paintintegerPoints in the paint.
points_in_the_paint_attemptedintegerNumber of points in the paint attempted.
points_in_the_paint_madeintegerNumber of points in the paint made.
points_in_the_paint_percentagenumericPoints in the paint percentage (0-1 decimal).
points_second_chanceintegerSecond-chance points scored.
rebounds_defensiveintegerDefensive rebounds.
rebounds_offensiveintegerOffensive rebounds.
rebounds_personalintegerRebounds personal.
rebounds_teamintegerRebounds team.
rebounds_team_defensiveintegerRebounds team defensive.
rebounds_team_offensiveintegerRebounds team offensive.
rebounds_totalintegerTotal rebounds.
second_chance_points_attemptedintegerNumber of second chance points attempted.
second_chance_points_madeintegerNumber of second chance points made.
second_chance_points_percentagenumericSecond chance points percentage (0-1 decimal).
stealsintegerTotal steals.
three_pointers_attemptedintegerThree-point field goal attempts.
three_pointers_madeintegerThree-point field goals made.
three_pointers_percentagenumericThree-point field goal percentage (0-1 decimal).
time_leadingcharacterTime leading.
times_tiedintegerTimes tied.
true_shooting_attemptsnumericNumber of true shooting attempted.
true_shooting_percentagenumericTrue shooting percentage (0-1).
turnoversintegerTotal turnovers.
turnovers_teamintegerTurnovers team.
turnovers_totalintegerTurnovers total.
two_pointers_attemptedintegerNumber of two pointers attempted.
two_pointers_madeintegerNumber of two pointers made.
two_pointers_percentagenumericTwo pointers percentage (0-1 decimal).

away_team_boxscore

Same columns as the home_team_boxscore table above.

home_team_player_boxscore

col_nametypesdescription
team_idintegerUnique team identifier.
team_namecharacterFull team display name (e.g. 'Las Vegas Aces').
team_citycharacterTeam city or region (e.g. 'Las Vegas').
team_tricodecharacterThree-letter team code (e.g. 'LAS' / 'NYL').
team_scoreintegerTeam's score / final score.
team_in_bonuscharacterTeam in bonus.
team_timeouts_remainingintegerTeam timeouts remaining.
statuscharacterStatus label.
orderintegerDisplay order within the result set.
person_idintegerUnique player identifier (V3 endpoints).
jersey_numcharacterJersey number worn by the player.
positioncharacterListed roster position (G, F, C, etc.).
startercharacterTRUE if the player was in the starting lineup; FALSE otherwise.
oncourtcharacterOncourt.
playedcharacterPlayed.
assistsintegerTotal assists.
blocksintegerTotal blocks.
blocks_receivedintegerShots blocked by opponents while attempting.
field_goals_attemptedintegerField goal attempts (2-pt + 3-pt).
field_goals_madeintegerField goals made (2-pt + 3-pt).
field_goals_percentagenumericField goal percentage (0-1 decimal).
fouls_offensiveintegerOffensive fouls.
fouls_drawnintegerPersonal fouls drawn (by opponent's actions).
fouls_personalintegerPersonal fouls.
fouls_technicalintegerTechnical fouls.
free_throws_attemptedintegerFree throw attempts.
free_throws_madeintegerFree throws made.
free_throws_percentagenumericFree throw percentage (0-1 decimal).
minusnumericMinus.
minutescharacterMinutes played, formatted MM:SS (V3 PT-duration parsed) or decimal minutes (V2).
minutes_calculatedcharacterMinutes calculated from game-clock differences.
plusnumericPlus.
plus_minus_pointsnumericPlus/minus point differential while on court.
pointsintegerPoints scored.
points_fast_breakintegerFast-break points scored.
points_in_the_paintintegerPoints in the paint.
points_second_chanceintegerSecond-chance points scored.
rebounds_defensiveintegerDefensive rebounds.
rebounds_offensiveintegerOffensive rebounds.
rebounds_totalintegerTotal rebounds.
stealsintegerTotal steals.
three_pointers_attemptedintegerThree-point field goal attempts.
three_pointers_madeintegerThree-point field goals made.
three_pointers_percentagenumericThree-point field goal percentage (0-1 decimal).
turnoversintegerTotal turnovers.
two_pointers_attemptedintegerNumber of two pointers attempted.
two_pointers_madeintegerNumber of two pointers made.
two_pointers_percentagenumericTwo pointers percentage (0-1 decimal).
namecharacterDisplay name.
name_icharacterInitialed name (e.g. 'A. Wilson').
first_namecharacterPlayer's first name.
family_namecharacterPlayer's family / last name.
not_playing_reasoncharacterNot playing reason.
not_playing_descriptioncharacterNot playing description.

away_team_player_boxscore

Same columns as the home_team_player_boxscore table above.

home_team_linescores

col_nametypesdescription
periodintegerPeriod of the game (1-4 quarters; 5+ for OT).
period_typecharacterPeriod type.
scoreintegerFinal score.

away_team_linescores

Same columns as the home_team_linescores table above.

Details

 nba_playbyplayv3(game_id = "0022201086")

 nba_pbp(game_id = '0022201086')
 nba_pbp(game_id = '0022201086', version = "v2")

y <- c("0022201086", "0022200021")

nba_pbps(game_ids = y)
nba_pbps(game_ids = y, version = "v2")

 nba_live_pbp(game_id = '0022201086')

 nba_live_boxscore(game_id = "0022201086")

See also

Other NBA PBP Functions: nba_data_pbp(), nba_schedule()

Other NBA Live Functions: nba_schedule()

Other NBA Boxscore Functions: nba_boxscoretraditionalv2(), nba_boxscoretraditionalv3()

Author

Saiem Gilani

Jason Lee