NBA — NBA Stats API (stats.nba.com) — Shot charts

nba_stats_shotchartdetail

GET /stats/shotchartdetail

Endpoint URL: GET https://stats.nba.com/stats/shotchartdetail

Valid URL: https://stats.nba.com/stats/shotchartdetail?ContextMeasure=FGA&DateFrom=&DateTo=&GameID=&GameSegment=&LastNGames=0&LeagueID=00&Location=&Month=0&OpponentTeamID=0&Outcome=&Period=0&PlayerID=202696&PlayerPosition=&RookieYear=&Season=2024-25&SeasonSegment=&SeasonType=Regular+Season&TeamID=0&VsConference=&VsDivision=

API Parameter	Python	Pattern	Required	Nullable	Description
AheadBehind	ahead_behind_nullable			Y
ClutchTime	clutch_time_nullable			Y
ContextFilter	context_filter_nullable			Y
ContextMeasure	context_measure_simple			Y
DateFrom	date_from_nullable			Y
DateTo	date_to_nullable			Y
EndPeriod	end_period_nullable			Y
EndRange	end_range_nullable			Y
GameID	game_id_nullable			Y
GameSegment	game_segment_nullable			Y
LastNGames	last_n_games			Y
LeagueID	league_id			Y
Location	location_nullable			Y
Month	month			Y
OpponentTeamID	opponent_team_id			Y
Outcome	outcome_nullable			Y
Period	period			Y
PlayerID	player_id			Y
PlayerPosition	player_position_nullable			Y
PointDiff	point_diff_nullable			Y
Position	position_nullable			Y
RangeType	range_type_nullable			Y
RookieYear	rookie_year_nullable			Y
Season	season_nullable			Y	Season label, e.g. 2024-25. Defaults at call time by a calendar cutoff, the month after a season's first games, so it can lag the newest rows by a few weeks. An NBA season tips off in late October and becomes the default in November (2025-26 through October 2026, 2026-27 from November 2026); a G League season (regular season from late December) in January; a Summer League (played in July, which stats.nba.com labels 2026-27 in 2026) in August; a draft combine (May) in June; a draft (drafthistory, a year; late June) in July. With season type Playoffs / PlayIn (or commonplayoffseries) the NBA and the G League roll over in May, after their playoffs start; with All Star the NBA rolls over in March, after the February game (the G League has no All-Star rows and keeps its own rule). A month table cannot follow a lockout or pandemic calendar (1998-99, 2011-12, 2020-21): pass a season then. Without one stats.nba.com answers an empty HTTP 500 or every season summed.
SeasonSegment	season_segment_nullable			Y
SeasonType	season_type_all_star			Y	Season type, a label: Regular Season, Pre Season, Playoffs, PlayIn or All Star (each endpoint takes a subset). Not ESPN's numeric code: 3 is HTTP 400. A default season follows it: Playoffs / PlayIn roll over in May (NBA, G League), All Star in March (NBA).
StartPeriod	start_period_nullable			Y
StartRange	start_range_nullable			Y
TeamID	team_id			Y
VsConference	vs_conference_nullable			Y
VsDivision	vs_division_nullable			Y

Returns

return_parsed=True (default) — A dict of DataFrames keyed by result-set name (Shot_Chart_Detail, LeagueAverages) (one table per documented key below); pass return_as_pandas=True for a dict of pandas.DataFrames (same keys).

Shot_Chart_Detail

col_name	type	description
grid_type	character	Shot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
game_id	character	Unique game identifier.
game_event_id	character	Unique identifier for game event.
player_id	character	Unique player identifier.
player_name	character	Player name.
team_id	character	Unique team identifier.
team_name	character	Full team display name (e.g. 'Las Vegas Aces').
period	character	Period of the game (1-4 quarters; 5+ for OT).
minutes_remaining	character	Minutes remaining.
seconds_remaining	character	Seconds remaining in the period.
event_type	character	Event / play type code (V2 PBP).
action_type	character	Action type label (e.g. 'Made Shot', 'Substitution').
shot_type	character	Shot type label (e.g. 'Jump Shot', 'Layup').
shot_zone_basic	character	Shot zone (e.g. 'Restricted Area', 'Mid-Range', 'Above the Break 3').
shot_zone_area	character	Shot zone area ('Left Side', 'Right Side', 'Center').
shot_zone_range	character	Shot zone range ('Less Than 8 ft.', '8-16 ft.', '16-24 ft.', etc.).
shot_distance	character	Shot distance from the basket, in feet.
loc_x	character	X coordinate on the court (units of inches; 0 = basket center).
loc_y	character	Y coordinate on the court (units of inches; baseline at 0).
shot_attempted_flag	character	1 if a shot was attempted on this event.
shot_made_flag	character	1 if the shot was made; 0 if missed.
game_date	character	Game date (YYYY-MM-DD).
htm	character	Home team abbreviation for the game.
vtm	character	Visiting team abbreviation for the game.

LeagueAverages

col_name	type	description
grid_type	character	Shot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
shot_zone_basic	character	Shot zone (e.g. 'Restricted Area', 'Mid-Range', 'Above the Break 3').
shot_zone_area	character	Shot zone area ('Left Side', 'Right Side', 'Center').
shot_zone_range	character	Shot zone range ('Less Than 8 ft.', '8-16 ft.', '16-24 ft.', etc.).
fga	integer	Field goal attempts.
fgm	integer	Field goals made.
fg_pct	numeric	Field goal percentage (0-1).

return_parsed=False — the raw JSON Dict payload, unparsed.

Example

nba_stats_shotchartdetail(league_id='00', season_nullable='2024-25')

Last validated n/a.

nba_stats_shotchartleaguewide

GET /stats/shotchartleaguewide

Endpoint URL: GET https://stats.nba.com/stats/shotchartleaguewide

Valid URL: https://stats.nba.com/stats/shotchartleaguewide?LeagueID=00&Season=2024-25

API Parameter	Python	Pattern	Required	Nullable	Description
LeagueID	league_id			Y
Season	season			Y	Season label, e.g. 2024-25. Defaults at call time by a calendar cutoff, the month after a season's first games, so it can lag the newest rows by a few weeks. An NBA season tips off in late October and becomes the default in November (2025-26 through October 2026, 2026-27 from November 2026); a G League season (regular season from late December) in January; a Summer League (played in July, which stats.nba.com labels 2026-27 in 2026) in August; a draft combine (May) in June; a draft (drafthistory, a year; late June) in July. With season type Playoffs / PlayIn (or commonplayoffseries) the NBA and the G League roll over in May, after their playoffs start; with All Star the NBA rolls over in March, after the February game (the G League has no All-Star rows and keeps its own rule). A month table cannot follow a lockout or pandemic calendar (1998-99, 2011-12, 2020-21): pass a season then. Without one stats.nba.com answers an empty HTTP 500 or every season summed.

Returns

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_name	type	description
grid_type	character	NBA or WNBA Stats value for grid type in the shotchartleaguewide result set.
shot_zone_basic	character	Shot zone (e.g. 'Restricted Area', 'Mid-Range', 'Above the Break 3').
shot_zone_area	character	Shot zone area ('Left Side', 'Right Side', 'Center').
shot_zone_range	character	Shot zone range ('Less Than 8 ft.', '8-16 ft.', '16-24 ft.', etc.).
fga	integer	Field goal attempts.
fgm	integer	Field goals made.
fg_pct	numeric	Field goal percentage (0-1).

return_parsed=False — the raw JSON Dict payload, unparsed.

Example

nba_stats_shotchartleaguewide(league_id='00', season='2024-25')

Last validated n/a.

nba_stats_shotchartlineupdetail

GET /stats/shotchartlineupdetail

Endpoint URL: GET https://stats.nba.com/stats/shotchartlineupdetail

Valid URL: https://stats.nba.com/stats/shotchartlineupdetail?ContextFilter=&ContextMeasure=FGA&DateFrom=&DateTo=&GROUP_ID=-202689-203493-203501-1626174-1627827-&GameID=&GameSegment=&LastNGames=0&LeagueID=00&Location=&Month=0&OpponentTeamID=0&Outcome=&Period=0&Season=2024-25&SeasonSegment=&SeasonType=Regular+Season&TeamID=0&VsConference=&VsDivision=

API Parameter	Python	Pattern	Required	Nullable	Description
ContextFilter	context_filter_nullable			Y
ContextMeasure	context_measure_detailed			Y
DateFrom	date_from_nullable			Y
DateTo	date_to_nullable			Y
GROUP_ID	group_id			Y
GameID	game_id_nullable			Y
GameSegment	game_segment_nullable			Y
LastNGames	last_n_games_nullable			Y
LeagueID	league_id			Y
Location	location_nullable			Y
Month	month_nullable			Y
OpponentTeamID	opponent_team_id_nullable			Y
Outcome	outcome_nullable			Y
Period	period			Y
Season	season			Y	Season label, e.g. 2024-25. Defaults at call time by a calendar cutoff, the month after a season's first games, so it can lag the newest rows by a few weeks. An NBA season tips off in late October and becomes the default in November (2025-26 through October 2026, 2026-27 from November 2026); a G League season (regular season from late December) in January; a Summer League (played in July, which stats.nba.com labels 2026-27 in 2026) in August; a draft combine (May) in June; a draft (drafthistory, a year; late June) in July. With season type Playoffs / PlayIn (or commonplayoffseries) the NBA and the G League roll over in May, after their playoffs start; with All Star the NBA rolls over in March, after the February game (the G League has no All-Star rows and keeps its own rule). A month table cannot follow a lockout or pandemic calendar (1998-99, 2011-12, 2020-21): pass a season then. Without one stats.nba.com answers an empty HTTP 500 or every season summed.
SeasonSegment	season_segment_nullable			Y
SeasonType	season_type_all_star			Y	Season type, a label: Regular Season, Pre Season, Playoffs, PlayIn or All Star (each endpoint takes a subset). Not ESPN's numeric code: 3 is HTTP 400. A default season follows it: Playoffs / PlayIn roll over in May (NBA, G League), All Star in March (NBA).
TeamID	team_id_nullable			Y
VsConference	vs_conference_nullable			Y
VsDivision	vs_division_nullable			Y

Returns

return_parsed=True (default) — A dict of DataFrames keyed by result-set name (ShotChartLineupDetail, ShotChartLineupLeagueAverage) (one table per documented key below); pass return_as_pandas=True for a dict of pandas.DataFrames (same keys).

ShotChartLineupDetail

col_name	type	description
grid_type	character	Shot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
game_id	character	Unique game identifier.
game_event_id	character	Unique identifier for game event.
group_id	character	ESPN group id.
group_name	character	The lineup's five players as a ' - ' separated string of abbreviated names.
player_id	character	Unique player identifier.
player_name	character	Player name.
team_id	character	Unique team identifier.
team_name	character	Full team display name (e.g. 'Las Vegas Aces').
period	character	Period of the game (1-4 quarters; 5+ for OT).
minutes_remaining	character	Minutes remaining.
seconds_remaining	character	Seconds remaining in the period.
event_type	character	Event / play type code (V2 PBP).
action_type	character	Action type label (e.g. 'Made Shot', 'Substitution').
shot_type	character	Shot type label (e.g. 'Jump Shot', 'Layup').
shot_zone_basic	character	Shot zone (e.g. 'Restricted Area', 'Mid-Range', 'Above the Break 3').
shot_zone_area	character	Shot zone area ('Left Side', 'Right Side', 'Center').
shot_zone_range	character	Shot zone range ('Less Than 8 ft.', '8-16 ft.', '16-24 ft.', etc.).
shot_distance	character	Shot distance from the basket, in feet.
loc_x	character	X coordinate on the court (units of inches; 0 = basket center).
loc_y	character	Y coordinate on the court (units of inches; baseline at 0).
shot_attempted_flag	character	1 if a shot was attempted on this event.
shot_made_flag	character	1 if the shot was made; 0 if missed.
game_date	character	Game date (YYYY-MM-DD).
htm	character	Home team abbreviation for the game.
vtm	character	Visiting team abbreviation for the game.

ShotChartLineupLeagueAverage

col_name	type	description
grid_type	character	Shot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
shot_zone_basic	character	Shot zone (e.g. 'Restricted Area', 'Mid-Range', 'Above the Break 3').
shot_zone_area	character	Shot zone area ('Left Side', 'Right Side', 'Center').
shot_zone_range	character	Shot zone range ('Less Than 8 ft.', '8-16 ft.', '16-24 ft.', etc.).
fga	integer	Field goal attempts.
fgm	integer	Field goals made.
fg_pct	numeric	Field goal percentage (0-1).

return_parsed=False — the raw JSON Dict payload, unparsed.

Example

nba_stats_shotchartlineupdetail(league_id='00', season='2024-25')

Last validated n/a.