NBA — additional Python functions — ESPN

espn_nba_game_rosters

espn_nba_game_rosters(game_id: 'int', raw=False, return_as_pandas=False, **kwargs) -> 'pl.DataFrame'

espn_nba_game_rosters() - Pull the game by id.

Parameters

Parameter	Type	Default	Description
game_id	int		Unique game_id, can be obtained from espn_nba_schedule().
raw		False
return_as_pandas	bool	False	If True, returns a pandas dataframe. If False, returns a polars dataframe.

Returns

Polars dataframe of game roster data with columns: 'athlete_id', 'athlete_uid', 'athlete_guid', 'athlete_type', 'first_name', 'last_name', 'full_name', 'athlete_display_name', 'short_name', 'weight', 'display_weight', 'height', 'display_height', 'age', 'date_of_birth', 'slug', 'jersey', 'linked', 'active', 'alternate_ids_sdr', 'birth_place_city', 'birth_place_state', 'birth_place_country', 'headshot_href', 'headshot_alt', 'experience_years', 'experience_display_value', 'experience_abbreviation', 'status_id', 'status_name', 'status_type', 'status_abbreviation', 'hand_type', 'hand_abbreviation', 'hand_display_value', 'draft_display_text', 'draft_round', 'draft_year', 'draft_selection', 'player_id', 'starter', 'valid', 'did_not_play', 'display_name', 'ejected', 'athlete_href', 'position_href', 'statistics_href', 'team_id', 'team_guid', 'team_uid', 'team_slug', 'team_location', 'team_name', 'team_abbreviation', 'team_display_name', 'team_short_display_name', 'team_color', 'team_alternate_color', 'is_active', 'is_all_star', 'logo_href', 'logo_dark_href', 'game_id'

col_name	type	description
athlete_id	integer	Unique athlete identifier (ESPN).
athlete_uid	character	ESPN athlete UID (universal identifier).
athlete_guid	character	ESPN athlete GUID.
athlete_type	character	Athlete type / class.
first_name	character	Player's first name.
last_name	character	Player's last name.
full_name	character	Player's full name.
athlete_display_name	character	Athlete display name (full).
short_name	character	Short display name.
weight	double	Player weight in pounds.
display_weight	character	Player weight in display format (e.g. '180 lbs').
height	double	Player height (string e.g. '6-2' or inches).
display_height	character	Player height in display format (e.g. '6-2').
age	integer	Player age (in years).
date_of_birth	character	Date of birth (YYYY-MM-DD).
debut_year	integer	Year of professional debut.
citizenship	character	Citizenship.
slug	character	URL-safe identifier.
jersey	character	Jersey number worn by the player.
linked	logical	TRUE if the record is linked to a related entity.
active	logical	TRUE if the row represents an active record (player / team / season).
alternate_ids_sdr	character
birth_place_city	character	Birth place city.
birth_place_country	character	Birth place country.
headshot_href	character	Headshot image URL.
headshot_alt	character	Alternative-text label for the headshot.
contracts_href	character
experience_years	integer	Experience years.
contract_href	character
contract_bird_status	integer	Contract bird status.
contract_base_year_compensation_active	logical	Contract base year compensation active.
contract_poison_pill_provision_active	logical
contract_incoming_trade_value	integer	Contract incoming trade value.
contract_outgoing_trade_value	integer	Contract outgoing trade value.
contract_minimum_salary_exception	logical	Contract minimum salary exception.
contract_option_type	integer	Contract option type.
contract_salary	integer	Contract salary.
contract_salary_remaining	integer	Contract salary remaining.
contract_years_remaining	integer	Contract years remaining.
contract_season_href	character
contract_team_href	character
contract_trade_kicker_active	logical	Contract trade kicker active.
contract_trade_kicker_percentage	double	Contract trade kicker percentage (0-1 decimal).
contract_trade_kicker_value	integer	Contract trade kicker value.
contract_trade_kicker_trade_value	integer	Contract trade kicker trade value.
contract_trade_restriction	logical	Contract trade restriction.
contract_unsigned_foreign_pick	logical	Contract unsigned foreign pick.
contract_active	logical	Contract active.
draft_display_text	character	Draft display text.
draft_round	integer	Round of the draft selection.
draft_year	integer	Draft year (4-digit).
draft_selection	integer	Draft selection.
draft_team_href	character
draft_pick_href	character
status_id	character	Status identifier.
status_name	character	Status label.
status_type	character	Status type.
status_abbreviation	character	Status abbreviation.
birth_place_state	character	Birth place state.
college_athlete_href	character
hand_type	character	Hand type.
hand_abbreviation	character	Hand abbreviation.
hand_display_value	character	Hand display value.
starter	logical	TRUE if the player was in the starting lineup; FALSE otherwise.
jersey_right	character
valid	logical	Valid.
did_not_play	logical	TRUE if the player did not appear in the game.
display_name	character	Display name.
reason	character	Reason.
ejected	logical	TRUE if the player was ejected from the game.
athlete_href	character
position_href	character
statistics_href	character
team_id	integer	Unique team identifier.
order	integer	Display order within the result set.
home_away	character	Game venue label ('home' or 'away').
winner	logical	Winner.
team_guid	character	ESPN team GUID.
team_uid	character	ESPN universal team identifier (UID format 's:40~l:...~t:...').
team_slug	character	URL-safe team identifier (e.g. 'lasvegas-aces' / 'aces').
team_location	character	Team city or location string.
team_name	character	Full team display name (e.g. 'Las Vegas Aces').
team_abbreviation	character	Short team abbreviation (e.g. 'LAS').
team_display_name	character	Full team display name.
team_short_display_name	character	Short team display name (e.g. 'Aces').
team_color	character	Team primary color (hex without leading '#').
team_alternate_color	character	Team alternate color (hex without leading '#').
is_active	logical	Is active.
is_all_star	logical	Is all star.
logo_href	character	Team or league logo URL.
logo_dark_href	character	Logo URL for dark backgrounds.
game_id	integer	Unique game identifier.

Example

from sportsdataverse.nba import espn_nba_game_rosters
rosters = espn_nba_game_rosters(game_id=401585183)
print(rosters.shape)

# Pandas round-trip

rosters_pd = espn_nba_game_rosters(game_id=401585183, return_as_pandas=True)
rosters_pd.head()

# Pipeline next step (filter to game starters)

import polars as pl
starters = espn_nba_game_rosters(game_id=401585183).filter(
    pl.col("starter") == True
)

espn_nba_pbp

espn_nba_pbp(game_id: 'int', raw=False, **kwargs) -> 'Dict'

espn_nba_pbp() - Pull the game by id - Data from API endpoints - nba/playbyplay, nba/summary

Parameters

Parameter	Type	Default	Description
game_id	int		Unique game_id, can be obtained from nba_schedule().
raw	bool	False	If True, returns the raw json from the API endpoint. If False, returns a cleaned dictionary of datasets.

Returns

Dictionary of game data with keys - "gameId", "plays", "winprobability", "boxscore", "header", "broadcasts", "videos", "playByPlaySource", "standings", "leaders", "seasonseries", "timeouts", "pickcenter", "againstTheSpread", "odds", "predictor", "espnWP", "gameInfo", "season"

Example

from sportsdataverse.nba import espn_nba_pbp
pbp = espn_nba_pbp(game_id=401585183)
print(list(pbp.keys()))

# Pull only the raw ESPN summary payload (skip cleaning)

raw_pbp = espn_nba_pbp(game_id=401585183, raw=True)

# Pipeline next step (load plays into a polars DataFrame)

import polars as pl
pbp = espn_nba_pbp(game_id=401585183)
plays_df = pl.from_dicts(pbp["plays"])

scoreboard_event_parsing

scoreboard_event_parsing(event)

Internal helper that flattens an ESPN NBA scoreboard event dict into a

shape suitable for pd.json_normalize.

Parameters

Parameter	Type	Default	Description
event	dict		A single scoreboard events[*] entry from the ESPN NBA scoreboard API.

Returns

The same event dict, mutated in place with home/away copies of the competitors and trimmed of unused link/odds keys.

Example

from sportsdataverse.nba import espn_nba_schedule
sched = espn_nba_schedule(dates=20230102)