Skip to contents

Fetch NBA Play-by-Play and Classify Field-Goal Attempts by Shot Zone

Source: R/nba_shot_zones.R
nba_shot_zones.Rd

Fetch NBA Play-by-Play and Classify Field-Goal Attempts by Shot Zone

Fetch NBA Play-by-Play and Classify Field-Goal Attempts by Shot Zone

Usage

nba_shot_zones(game_id, ...)

Arguments

game_id

A length-1 character string - the ten-character NBA Stats game identifier (e.g. "0022200001" for the first game of the 2022-23 regular season).

...

Reserved for future keyword arguments (currently ignored).

Value

Returns a data.frame containing the full V3 play-by-play for game_id with an appended shot_zone column:

col_nametypesdescription
event_typecharacterPlay event type code. "1" = MadeShot, "2" = MissedShot, "3" = FreeThrow, etc.
shot_valueintegerPoint value of the shot attempt (2 or 3); 0 for non-FGA events.
x_legacynumericHorizontal court coordinate (legacy units). Negative = left side of the court.
y_legacynumericVertical court coordinate (legacy units). Values near 0 = baseline.
shot_distancenumericDistance from the basket in feet.
shot_zonecharacterShot-zone classification. One of "corner_3", "above_the_break_3", "restricted_area", "in_the_paint_non_ra", "mid_range". NA on non-field-goal rows.

All other columns from the V3 PBP schema (nba_pbp()) are also present. Returns a 0-row frame when the game cannot be fetched (never-raise).

Shot zone definitions (pbpstats-core aligned):

  • "corner_3" - three-point attempt with abs(x_legacy) >= 220 and y_legacy <= 87.5 (baseline corner area).

  • "above_the_break_3" - all other three-point attempts.

  • "restricted_area" - two-point attempt within 4 ft of the basket.

  • "in_the_paint_non_ra" - two-point attempt 4-8 ft from the basket and within 80 legacy units of the paint center (abs(x_legacy) <= 80).

  • "mid_range" - all remaining two-point attempts.

Details

 df <- nba_shot_zones(game_id = "0022200001")
 print(table(df$shot_zone, useNA = "ifany"))

See also

Other NBA Lineup Functions: nba_boxscoretraditionalv3(), nba_fantasywidget(), nba_possession_lineups(), nba_rapm(), nba_shotchartdetail(), nba_teamdashboardbyclutch()

Author

Saiem Gilani

Examples

if (FALSE) { # interactive()
# \donttest{
  try({
    df <- nba_shot_zones(game_id = "0022200001")
    print(df[!is.na(df$shot_zone), c("shot_distance", "shot_zone")])
  })
# }
}