NBA — ESPN web API (v3)

sportsdataverse.nba — 5 endpoints.

espn_nba_player_overview

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/{athlete_id}/overview

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/4239/overview

API Parameter	Python	Pattern	Required	Nullable	Description
athlete_id	athlete_id		Y		athlete_id path parameter.

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
athlete_id	integer	Unique athlete identifier (ESPN).
athlete_display_name	character	Athlete display name (full).
athlete_short_name	character	Athlete short display name.
athlete_position	character	Athlete position.
athlete_jersey	character	Athlete jersey number.
athlete_team_id	integer
athlete_team_abbreviation	character
split_name	character	Split name (typically "All Splits").
split_category	character
games_played	character	Games played.
avg_minutes	character
field_goal_pct	character	Field goal percentage (0-1).
three_point_pct	character
free_throw_pct	character	Free throw percentage (0-1).
avg_rebounds	character
avg_assists	character
avg_blocks	character
avg_steals	character
avg_fouls	character
avg_turnovers	character
avg_points	character

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

Raises

Exception	Description
NoDataError	The host answered 404 -- the requested resource does not exist.
ValueError	The host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchError	The 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.

Example

espn_nba_player_overview(athlete_id='4239')

espn_nba_player_stats_v3

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/{athlete_id}/stats

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/4239/stats

API Parameter	Python	Pattern	Required	Nullable	Description
athlete_id	athlete_id		Y		athlete_id path parameter.
season	season			Y	Season year (e.g. 2024).

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
category	character	ESPN stat category the row belongs to (e.g., basketball "averages" / "totals" / "miscellaneous", NFL "passing", MLB "career-batting"). The stat columns after position are named from each category's own names list, so they differ by sport, and the other categories' columns are null on a row.
split_name	character	Season label of the row (e.g., "2010-11") on the Web v3 payload, or "Career" on the row built from the category's career totals; the split's name on payloads that ship named splits.
split_category	character	Category of a named split; null on the Web v3 per-season rows.
split_value	character	Value of a named split; null on the Web v3 per-season rows.
season	integer	Season end year of the row (e.g., 2011 for 2010-11); null on the "Career" row.
team_id	integer	ESPN team id (Int64) the athlete played that season for; a traded player has one row per team. Null on the "Career" row.
position	character	Position abbreviation the athlete was listed at for that season and team (e.g., "G"); null on the "Career" row.
games_played	character	Games played (GP), as ESPN ships it (a string).
games_started	character	Games started (GS).
avg_minutes	character	Minutes per game (MIN).
avg_field_goals_made_avg_field_goals_attempted	character	Field goals made-attempted per game (FG), one "made-attempted" string (e.g., "3.9-9.0").
field_goal_pct	character	Field goal percentage (FG%), FGM / FGA x 100.
avg_three_point_field_goals_made_avg_three_point_field_goals_attempted	character	Three-point field goals made-attempted per game (3PT), one "made-attempted" string.
three_point_field_goal_pct	character	Three-point field goal percentage (3P%), 3PM / 3PA x 100.
avg_free_throws_made_avg_free_throws_attempted	character	Free throws made-attempted per game (FT), one "made-attempted" string.
free_throw_pct	character	Free throw percentage (FT%), FTM / FTA x 100.
avg_offensive_rebounds	character	Offensive rebounds per game (OR).
avg_defensive_rebounds	character	Defensive rebounds per game (DR).
avg_rebounds	character	Rebounds per game (REB).
avg_assists	character	Assists per game (AST).
avg_blocks	character	Blocks per game (BLK).
avg_steals	character	Steals per game (STL).
avg_fouls	character	Personal fouls per game (PF).
avg_turnovers	character	Turnovers per game (TO).
avg_points	character	Points per game (PTS).
field_goals_made_field_goals_attempted	character	Season field goals made-attempted (FG), one "made-attempted" string.
three_point_field_goals_made_three_point_field_goals_attempted	character	Season three-point field goals made-attempted (3PT), one "made-attempted" string.
free_throws_made_free_throws_attempted	character	Season free throws made-attempted (FT), one "made-attempted" string.
offensive_rebounds	character	Season offensive rebounds (OR).
defensive_rebounds	character	Season defensive rebounds (DR).
total_rebounds	character	Season rebounds (REB).
assists	character	Season assists (AST).
blocks	character	Season blocked shots (BLK).
steals	character	Season steals (STL).
fouls	character	Season personal fouls (PF).
turnovers	character	Season turnovers (TO).
points	character	Season points (PTS).
double_double	character	Games with double figures in two of points, rebounds, assists, steals and blocks (DD2).
triple_double	character	Games with double figures in three of points, rebounds, assists, steals and blocks (TD3).
disqualifications	character	Times the athlete fouled out (DQ).
ejections	character	Times the athlete was ejected (EJECT).
technical_fouls	character	Technical fouls called on the athlete (TECH).
flagrant_fouls	character	Flagrant fouls called on the athlete (FLAG).
assist_turnover_ratio	character	Assists per turnover (AST/TO).
steal_turnover_ratio	character	Steals per turnover (STL/TO).
scoring_efficiency	character	ESPN's scoring efficiency (SC-EFF).
shooting_efficiency	character	ESPN's shooting efficiency (SH-EFF).

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

Raises

Exception	Description
NoDataError	The host answered 404 -- the requested resource does not exist.
ValueError	The host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchError	The 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.

Example

espn_nba_player_stats_v3(athlete_id='4239')

espn_nba_player_gamelog

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/{athlete_id}/gamelog

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/4239/gamelog

API Parameter	Python	Pattern	Required	Nullable	Description
athlete_id	athlete_id		Y		athlete_id path parameter.
season	season			Y	Season year (e.g. 2024).

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
season_type_id	integer	Unique identifier for season type.
season_type_name	character	Season type name.
category	character	Category label.
event_id	integer	Unique event / game identifier (ESPN).
event_date	character
home_away	character	Game venue label ('home' or 'away').
score	character	Final score.
opponent_id	integer	Unique identifier for opponent.
opponent_abbreviation	character
opponent_display_name	character
game_result	character
game_processed	character
stat_0	character
stat_1	character
stat_2	character
stat_3	character
stat_4	character
stat_5	character
stat_6	character
stat_7	character
stat_8	character
stat_9	character
stat_10	character
stat_11	character
stat_12	character
stat_13	character

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

Raises

Exception	Description
NoDataError	The host answered 404 -- the requested resource does not exist.
ValueError	The host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchError	The 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.

Example

espn_nba_player_gamelog(athlete_id='4239')

espn_nba_player_splits

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/{athlete_id}/splits

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/4239/splits

API Parameter	Python	Pattern	Required	Nullable	Description
athlete_id	athlete_id		Y		athlete_id path parameter.
season	season			Y	Season year (e.g. 2024).

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
descriptions	character
display_name	character	Display name.
display_names	character
filters	character
labels	character
names	character	Names.
split_categories	character

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

Raises

Exception	Description
NoDataError	The host answered 404 -- the requested resource does not exist.
ValueError	The host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchError	The 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.

Example

espn_nba_player_splits(athlete_id='4239')

espn_nba_leaders

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/statistics/byathlete

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/nba/statistics/byathlete?limit=50&page=1

API Parameter	Python	Pattern	Required	Nullable	Description
category	category			Y	Leaderboard population: the athletes ranked in that category, whose values it fills (other categories come back null). Football takes <group>:<category> (offense:passing, offense:rushing, offense:receiving, defense:defensive, scoring:scoring); a bare passing is rejected with HTTP 400 (ValueError). Basketball takes the bare name (offensive).
season	season			Y	Season year (e.g. 2024).
seasontype	season_type			Y	Season phase: 1=preseason, 2=regular season, 3=postseason.
limit	limit			Y	Maximum number of items to return.
page	page			Y	page query parameter.
sort	sort			Y	Sort key <category>.<statName>:<asc|desc>, the names in the payload's categories (passing.passingYards:desc, offensive.avgPoints:desc). A stat without its category is rejected with HTTP 400 (ValueError).

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
sort_order	integer	Position of the athlete in ESPN's leaderboard order (the requested category or sort), counted across pages: (page - 1) * limit + position on the page. A position, not a rank: tied athletes still count up; ESPN's per-stat ranks stay in the raw payload (return_parsed=False).
athlete_id	integer	ESPN id of the athlete, the key the athlete endpoints (athlete_overview, athlete_stats) take.
athlete_uid	character	ESPN composite athlete uid (s:<sport>~l:<league>~a:<athlete id>), kept as text.
athlete_display_name	character	Athlete's full display name.
athlete_short_name	character	Athlete's abbreviated name (e.g. 'B. Nix').
athlete_first_name	character	Athlete's first name.
athlete_last_name	character	Athlete's last name.
athlete_position	character	Athlete's position abbreviation (e.g. QB, G, C).
athlete_status	character	Athlete's ESPN status name (e.g. Active, Inactive) as ESPN reports it at request time, not for the requested season.
team_id	integer	ESPN id of the team the athlete played for in the requested season.
team_abbreviation	character	Abbreviation of the athlete's team in the requested season (ESPN teamShortName, e.g. ORE).
team_name	character	Nickname of the athlete's team in the requested season (ESPN teamName, e.g. Ducks).
general_games_played	double	Games Played (ESPN 'general' category).
general_avg_minutes	double	Minutes Per Game (ESPN 'general' category): The average number of minutes per game.
general_avg_fouls	double	Fouls Per Game (ESPN 'general' category): The average fouls committed per game.
general_flagrant_fouls	double	Flagrant Fouls (ESPN 'general' category): The number of fouls that the officials thought were unnecessary or excessive.
general_technical_fouls	double	Technical Fouls (ESPN 'general' category): The number of times an player or coach was called for a technical foul (unsportsmanlike conduct or violations).
general_ejections	double	Ejections (ESPN 'general' category): The number of times a player or coach is removed from the game as a result of a serious offense.
general_double_double	double	Double Double (ESPN 'general' category): The number of times double digit values were accumulated in 2 of the following categories: points, rebounds, assists, steals, and blocked shots.
general_triple_double	double	Triple Double (ESPN 'general' category): The number of times double digit values were accumulated in 3 of the following categories: points, rebounds, assists, steals, and blocked shots.
general_minutes	double	Minutes (ESPN 'general' category): The total number of minutes played.
general_rebounds	double	Rebounds (ESPN 'general' category): The total number of rebounds (offensive and defensive).
general_fouls	double	Fouls (ESPN 'general' category): The number of times a player had illegal contact with the opponent.
general_avg_rebounds	double	Rebounds Per Game (ESPN 'general' category): The average rebounds per game.
offensive_avg_points	double	Points Per Game (ESPN 'offensive' category): The average number of points scored per game.
offensive_avg_field_goals_made	double	Average Field Goals Made (ESPN 'offensive' category): The average field goals made per game.
offensive_avg_field_goals_attempted	double	Average Field Goals Attempted (ESPN 'offensive' category): The average field goals attempted per game.
offensive_field_goal_pct	double	Field Goal Percentage (ESPN 'offensive' category): The ratio of field goals made to field goals attempted: FGM / FGA.
offensive_avg_three_point_field_goals_made	double	Average 3-Point Field Goals Made (ESPN 'offensive' category): The average three point field goals made per game.
offensive_avg_three_point_field_goals_attempted	double	Average 3-Point Field Goals Attempted (ESPN 'offensive' category): The average three point field goals attempted per game.
offensive_three_point_field_goal_pct	double	3-Point Field Goal Percentage (ESPN 'offensive' category): The ratio of 3pt field goals made to 3pt field goals attempted: 3PM / 3PA.
offensive_avg_free_throws_made	double	Average Free Throws Made (ESPN 'offensive' category): The average free throw shots made per game.
offensive_avg_free_throws_attempted	double	Average Free Throws Attempted (ESPN 'offensive' category): The average free throw shots attempted per game.
offensive_free_throw_pct	double	Free Throw Percentage (ESPN 'offensive' category): The ratio of free throws made to free throws attempted: FTM / FTA.
offensive_avg_assists	double	Assists Per Game (ESPN 'offensive' category): The average assists per game.
offensive_avg_turnovers	double	Turnovers Per Game (ESPN 'offensive' category): The average turnovers committed per game.
offensive_points	double	Points (ESPN 'Points', offensive category): points scored in basketball; goals plus assists in hockey.
offensive_field_goals_made	double	Field Goals Made (ESPN 'offensive' category): The number of times a 2pt field goal was made.
offensive_field_goals_attempted	double	Field Goals Attempted (ESPN 'offensive' category): The number of times a 2pt field goal was attempted.
offensive_three_point_field_goals_made	double	3-Point Field Goals Made (ESPN 'offensive' category): The number of times a 3pt field goal was made.
offensive_three_point_field_goals_attempted	double	3-Point Field Goals Attempted (ESPN 'offensive' category): The number of times a 3pt field goal was attempted.
offensive_free_throws_made	double	Free Throws Made (ESPN 'offensive' category): The number of times a free throw was made.
offensive_free_throws_attempted	double	Free Throws Attempted (ESPN 'offensive' category): The number of times a free throw was attempted.
offensive_assists	double	Assists (ESPN 'Assists', offensive category): passes that lead directly to a score in basketball; goal assists in hockey.
offensive_turnovers	double	Turnovers (ESPN 'offensive' category): The number of times a player loses possession to the other team.
defensive_avg_steals	double	Steals Per Game (ESPN 'defensive' category): The average steals per game.
defensive_avg_blocks	double	Blocks Per Game (ESPN 'defensive' category): The average blocks per game.
defensive_steals	double	Steals (ESPN 'defensive' category): The number of times a defensive player forced a turnover by intercepting or deflecting a pass or a dribble of an offensive player.
defensive_blocks	double	Blocks (ESPN 'defensive' category): Short for blocked shot, number of times when a defensive player legally deflects a field goal attempt from an offensive player.

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

Raises

Exception	Description
NoDataError	The host answered 404 -- the requested resource does not exist.
ValueError	The host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchError	The 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.

Example

espn_nba_leaders()