Skip to main content

NBA G League — G League Stats API (stats.nba.com, LeagueID=20) — Shot charts

nbagl_stats_shotchartdetail​

Shot chart detail.

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=20&Location=&Month=0&OpponentTeamID=0&Outcome=&Period=0&PlayerID=1642443&PlayerPosition=&RookieYear=&Season=2024-25&SeasonSegment=&SeasonType=Regular+Season&TeamID=0&VsConference=&VsDivision=

API ParameterPythonPatternRequiredNullableDescription
AheadBehindahead_behind_nullableY
ClutchTimeclutch_time_nullableY
ContextFiltercontext_filter_nullableY
ContextMeasurecontext_measure_simpleY
DateFromdate_from_nullableY
DateTodate_to_nullableY
EndPeriodend_period_nullableY
EndRangeend_range_nullableY
GameIDgame_id_nullableY
GameSegmentgame_segment_nullableY
LastNGameslast_n_gamesY
LeagueIDleague_idY
Locationlocation_nullableY
MonthmonthY
OpponentTeamIDopponent_team_idY
Outcomeoutcome_nullableY
PeriodperiodY
PlayerIDplayer_idY
PlayerPositionplayer_position_nullableY
PointDiffpoint_diff_nullableY
Positionposition_nullableY
RangeTyperange_type_nullableY
RookieYearrookie_year_nullableY
Seasonseason_nullableYSeason 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. A G League regular season starts in late December and becomes the default in January (2025-26 from January 2026); a draft combine (May) in June. With season type Playoffs (or commonplayoffseries) it rolls over in May, after the late-March playoffs start; the G League has no All-Star rows. A month table cannot follow a lockout or pandemic calendar: pass a season then. Without one stats.nba.com answers an empty HTTP 500 or every season summed.
SeasonSegmentseason_segment_nullableY
SeasonTypeseason_type_all_starYSeason type, a label: Regular Season, Pre Season or Playoffs (each endpoint takes a subset; the G League has no All Star rows). Not ESPN's numeric code: 3 is HTTP 400. A default season follows it: Playoffs rolls over in May.
StartPeriodstart_period_nullableY
StartRangestart_range_nullableY
TeamIDteam_idY
VsConferencevs_conference_nullableY
VsDivisionvs_division_nullableY

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_nametypedescription
grid_typeStringShot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
game_idString
game_event_idString
player_idString
player_nameString
team_idString
team_nameString
periodString
minutes_remainingString
seconds_remainingString
event_typeString
action_typeString
shot_typeString
shot_zone_basicString
shot_zone_areaString
shot_zone_rangeString
shot_distanceString
loc_xString
loc_yString
shot_attempted_flagString
shot_made_flagString
game_dateString
htmStringHome team abbreviation for the game.
vtmStringVisiting team abbreviation for the game.

LeagueAverages

col_nametypedescription
grid_typeStringShot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
shot_zone_basicString
shot_zone_areaString
shot_zone_rangeString
fgaInt64
fgmInt64
fg_pctFloat64

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

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.
ImportErrorcurl_cffi is not installed -- stats.nba.com / stats.wnba.com block plain requests, so the transport needs it (pip install curl_cffi or sportsdataverse[all]).

Example​

nbagl_stats_shotchartdetail(league_id='20', season_nullable='2024-25')

nbagl_stats_shotchartleaguewide​

Shot chart league wide.

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

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

API ParameterPythonPatternRequiredNullableDescription
LeagueIDleague_idY
SeasonseasonYSeason 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. A G League regular season starts in late December and becomes the default in January (2025-26 from January 2026); a draft combine (May) in June. With season type Playoffs (or commonplayoffseries) it rolls over in May, after the late-March playoffs start; the G League has no All-Star rows. A month table cannot follow a lockout or pandemic calendar: 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_nametypedescription
grid_typeStringNBA or WNBA Stats value for grid type in the shotchartleaguewide result set.
shot_zone_basicString
shot_zone_areaString
shot_zone_rangeString
fgaInt64
fgmInt64
fg_pctFloat64

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

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.
ImportErrorcurl_cffi is not installed -- stats.nba.com / stats.wnba.com block plain requests, so the transport needs it (pip install curl_cffi or sportsdataverse[all]).

Example​

nbagl_stats_shotchartleaguewide(league_id='20', season='2024-25')

nbagl_stats_shotchartlineupdetail​

Shot chart lineup detail.

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

API ParameterPythonPatternRequiredNullableDescription
ContextFiltercontext_filter_nullableY
ContextMeasurecontext_measure_detailedY
DateFromdate_from_nullableY
DateTodate_to_nullableY
GROUP_IDgroup_idYGROUP_ID: required; there is no G League default for it.
GameIDgame_id_nullableY
GameSegmentgame_segment_nullableY
LastNGameslast_n_games_nullableY
LeagueIDleague_idY
Locationlocation_nullableY
Monthmonth_nullableY
OpponentTeamIDopponent_team_id_nullableY
Outcomeoutcome_nullableY
PeriodperiodY
SeasonseasonYSeason 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. A G League regular season starts in late December and becomes the default in January (2025-26 from January 2026); a draft combine (May) in June. With season type Playoffs (or commonplayoffseries) it rolls over in May, after the late-March playoffs start; the G League has no All-Star rows. A month table cannot follow a lockout or pandemic calendar: pass a season then. Without one stats.nba.com answers an empty HTTP 500 or every season summed.
SeasonSegmentseason_segment_nullableY
SeasonTypeseason_type_all_starYSeason type, a label: Regular Season, Pre Season or Playoffs (each endpoint takes a subset; the G League has no All Star rows). Not ESPN's numeric code: 3 is HTTP 400. A default season follows it: Playoffs rolls over in May.
TeamIDteam_id_nullableY
VsConferencevs_conference_nullableY
VsDivisionvs_division_nullableY

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_nametypedescription
grid_typeStringShot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
game_idString
game_event_idString
group_idString
group_nameStringThe lineup's five players as a ' - ' separated string of abbreviated names.
player_idString
player_nameString
team_idString
team_nameString
periodString
minutes_remainingString
seconds_remainingString
event_typeString
action_typeString
shot_typeString
shot_zone_basicString
shot_zone_areaString
shot_zone_rangeString
shot_distanceString
loc_xString
loc_yString
shot_attempted_flagString
shot_made_flagString
game_dateString
htmStringHome team abbreviation for the game.
vtmStringVisiting team abbreviation for the game.

ShotChartLineupLeagueAverage

col_nametypedescription
grid_typeStringShot chart grid type label returned by the stats API (e.g. "Shot Chart Detail").
shot_zone_basicString
shot_zone_areaString
shot_zone_rangeString
fgaInt64
fgmInt64
fg_pctFloat64

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

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.
ImportErrorcurl_cffi is not installed -- stats.nba.com / stats.wnba.com block plain requests, so the transport needs it (pip install curl_cffi or sportsdataverse[all]).

Example​

nbagl_stats_shotchartlineupdetail(league_id='20', season='2024-25')