MBB — additional Python functions

Hand-written wrappers, loaders, and helpers in sportsdataverse.mbb not covered by the generated API-endpoint reference above.

Play-by-play, schedule & rosters

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

espn_mbb_game_rosters() - Pull the game by id.

Parameters

Parameter	Type	Default	Description
game_id	int		Unique game_id, can be obtained from mbb_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_nickname', 'team_abbreviation', 'team_display_name', 'team_short_display_name', 'team_color', 'team_alternate_color', 'is_active', 'is_all_star', 'team_alternate_ids_sdr', '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).
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	Alternate ids sdr.
birth_place_city	character	Birth place city.
birth_place_state	character	Birth place state.
birth_place_country	character	Birth place country.
birth_country_alternate_id	character
birth_country_abbreviation	character	Birth country abbreviation.
headshot_href	character	Headshot image URL.
headshot_alt	character	Alternative-text label for the headshot.
flag_href	character
flag_alt	character
flag_rel	character
experience_years	integer	Experience years.
experience_display_value	character	Experience display value.
experience_abbreviation	character	Experience abbreviation.
status_id	character	Status identifier.
status_name	character	Status label.
status_type	character	Status type.
status_abbreviation	character	Status abbreviation.
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.
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_nickname	character	Team nickname.
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.
team_alternate_ids_sdr	character
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.mbb import espn_mbb_game_rosters
roster = espn_mbb_game_rosters(game_id=401638637)
print(roster.shape)

# Identify starters

import polars as pl
starters = roster.filter(pl.col("starter") == True).select(
    ["full_name", "jersey", "team_display_name"]
)

# Pandas round-trip

roster_pd = espn_mbb_game_rosters(game_id=401638637, return_as_pandas=True)
roster_pd.head()

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

espn_mbb_pbp() - Pull the game by id. Data from API endpoints: mens-college-basketball/playbyplay, mens-college-basketball/summary

Parameters

Parameter	Type	Default	Description
game_id	int		Unique game_id, can be obtained from mbb_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", "timeouts", "pickcenter", "againstTheSpread", "odds", "predictor", "espnWP", "gameInfo", "season"

Example

from sportsdataverse.mbb import espn_mbb_pbp
game = espn_mbb_pbp(game_id=401638637)
print(game["gameId"])
print(len(game["plays"]))

# Filter shooting plays for a basic shot chart

import polars as pl
plays = pl.DataFrame(game["plays"])
shots = plays.filter(pl.col("shooting_play") == True)
shots.select(
    [
        "period_number",
        "clock_display_value",
        "team_id",
        "coordinate_x",
        "coordinate_y",
        "score_value",
        "text",
    ]
).head()

# Convert to pandas

import pandas as pd
plays_pd = pd.DataFrame(game["plays"])
plays_pd[plays_pd["shooting_play"] == True].head()

# Raw payload (skip the cleaning pipeline) for debugging

raw = espn_mbb_pbp(game_id=401638637, raw=True)
sorted(raw.keys())

espn_mbb_player_stats(athlete_id: 'int', season: 'int', *, season_type: 'str' = 'regular', total: 'bool' = False, raw: 'bool' = False, return_as_pandas: 'bool' = False, **kwargs: 'Any') -> 'pl.DataFrame | pd.DataFrame | dict[str, Any]'

Pull a men's-college-basketball athlete's ESPN season stat line.

See sportsdataverse.wbb.espn_wbb_player_stats for full documentation of the wide return shape, the {category}_{stat} stat columns, the athlete / team metadata blocks, and the season_type / total parameters. For the richer web-v3 payload use sportsdataverse.mbb.espn_mbb_player_stats_v3.

Parameters

Parameter	Type	Default	Description
athlete_id	int		ESPN men's-college-basketball athlete identifier.
season	int		Season year, used in the core-v2 path.
season_type	str	'regular'	"regular" (type 2) or "postseason" (type 3).
total	bool	False	Forward-compat totals passthrough.
raw	bool	False	If True, returns the raw core-v2 statistics JSON dict.
return_as_pandas	bool	False	If True, returns a pandas DataFrame; else polars.

Returns

A single-row wide DataFrame (polars by default). When raw=True returns the raw statistics JSON dict.

col_name	type	description
season	integer	Season year.
season_type	character	Season type (1=pre-season, 2=regular season, 3=postseason, 4=off-season for ESPN; or string label for WNBA Stats).
total	logical	Total.
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.
display_name	character	Display name.
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	character	Player age (in years).
date_of_birth	character	Date of birth (YYYY-MM-DD).
jersey	character	Jersey number worn by the player.
slug	character	URL-safe identifier.
active	logical	TRUE if the row represents an active record (player / team / season).
position_id	integer	Unique position identifier.
position_name	character	Listed roster position ('Guard', 'Forward', 'Center').
position_display_name	character	Position display name.
position_abbreviation	character	Position abbreviation ('G' / 'F' / 'C').
college_name	character	College name.
status_id	integer	Status identifier.
status_name	character	Status label.
defensive_blocks	double	Short for blocked shot, number of times when a defensive player legally deflects a field goal attempt from an offensive player.
defensive_defensive_rebounds	double	The number of times when the defense obtains the possession of the ball after a missed shot by the offense.
defensive_steals	double	The number of times a defensive player forced a turnover by intercepting or deflecting a pass or a dribble of an offensive player.
defensive_turnover_points	double	The amount of points resulting from the possession following a turnover.
defensive_avg_defensive_rebounds	double	The average defensive rebounds per game.
defensive_avg_blocks	double	The average blocks per game.
defensive_avg_steals	double	The average steals per game.
general_disqualifications	double	The number of times a player reached the foul limit.
general_flagrant_fouls	double	The number of fouls that the officials thought were unnecessary or excessive.
general_fouls	double	The number of times a player had illegal contact with the opponent.
general_per	double	A numerical value for each of a player's accomplishments per-minute and is pace-adjusted for the team they play on. The league average in PER to 15.00 every season.
general_ejections	double	The number of times a player or coach is removed from the game as a result of a serious offense.
general_technical_fouls	double	The number of times an player or coach was called for a technical foul (unsportsmanlike conduct or violations).
general_rebounds	double	The total number of rebounds (offensive and defensive).
general_minutes	double	The total number of minutes played.
general_avg_minutes	double	The average number of minutes per game.
general_fantasy_rating	double	The Fantasy Rating of a player.
general_plus_minus	double	A player's estimated on-court impact on team performance measured in point differential per 100 possessions.
general_avg_rebounds	double	The average rebounds per game.
general_avg_fouls	double	The average fouls committed per game.
general_avg_flagrant_fouls	double	The average number of flagrant fouls per game.
general_avg_technical_fouls	double	The average number of technical fouls per game.
general_avg_ejections	double	The average ejections per game.
general_avg_disqualifications	double	The average number of disqualifications per game.
general_assist_turnover_ratio	double	The average number of assists a player or team records per turnover.
general_steal_foul_ratio	double	The average number of steals a player or team records per foul committed.
general_block_foul_ratio	double	The average number of blocks a player or record per foul committed.
general_avg_team_rebounds	double	The average number of rebounds for a team per game.
general_total_rebounds	double	The total number of rebounds for a team or player.
general_total_technical_fouls	double	The total number of technical fouls for a team or player.
general_steal_turnover_ratio	double	The number of steals per turnover.
general_games_played	double	Games Played.
general_games_started	double	The number of games started by an athlete.
general_double_double	double	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	The number of times double digit values were accumulated in 3 of the following categories: points, rebounds, assists, steals, and blocked shots.
offensive_assists	double	The number of times a player who passes the ball to a teammate in a way that leads to a score by field goal, meaning that he or she was "assisting" in the basket. There is some judgment involved in deciding whether a passer should be credited with an assist.
offensive_field_goals	double	Field Goal makes and attempts.
offensive_field_goals_attempted	double	The number of times a 2pt field goal was attempted.
offensive_field_goals_made	double	The number of times a 2pt field goal was made.
offensive_field_goal_pct	double	The ratio of field goals made to field goals attempted: FGM / FGA.
offensive_free_throws	double	Free Throw makes and attempts.
offensive_free_throw_pct	double	The ratio of free throws made to free throws attempted: FTM / FTA.
offensive_free_throws_attempted	double	The number of times a free throw was attempted.
offensive_free_throws_made	double	The number of times a free throw was made.
offensive_offensive_rebounds	double	The number of times when the offense obtains the possession of the ball after a missed shot.
offensive_points	double	The number of points scored.
offensive_turnovers	double	The number of times a player loses possession to the other team.
offensive_three_point_field_goals_attempted	double	The number of times a 3pt field goal was attempted.
offensive_three_point_field_goals_made	double	The number of times a 3pt field goal was made.
offensive_total_turnovers	double	The number of turnovers plus team turnovers for the team.
offensive_points_in_paint	double	The amount of points scored in the area known as "the Paint"(the rectangle between the foul line and the baseline).
offensive_second_chance_points	double
offensive_fast_break_points	double	The number of points scored on fast breaks.
offensive_avg_field_goals_made	double	The average field goals made per game.
offensive_avg_field_goals_attempted	double	The average field goals attempted per game.
offensive_avg_three_point_field_goals_made	double	The average three point field goals made per game.
offensive_avg_three_point_field_goals_attempted	double	The average three point field goals attempted per game.
offensive_avg_free_throws_made	double	The average free throw shots made per game.
offensive_avg_free_throws_attempted	double	The average free throw shots attempted per game.
offensive_avg_points	double	The average number of points scored per game.
offensive_avg_offensive_rebounds	double	The average offensive rebounds per game.
offensive_avg_assists	double	The average assists per game.
offensive_avg_turnovers	double	The average turnovers committed per game.
offensive_offensive_rebound_pct	double	The percentage of the number of times they obtain the possession of the ball after a missed shot.
offensive_estimated_possessions	double	An estimation of the number of possessions for a team or player.
offensive_avg_estimated_possessions	double	The average number of estimated possessions per game for a team or player.
offensive_points_per_estimated_possessions	double	The number of points per estimated possession for a team or player.
offensive_avg_team_turnovers	double	The average number of turnovers for a team per game.
offensive_avg_total_turnovers	double	The average number of total turnovers for a team per game.
offensive_three_point_field_goal_pct	double	The ratio of 3pt field goals made to 3pt field goals attempted: 3PM / 3PA.
offensive_two_point_field_goals_made	double	The number of 2-point field goals made for a team or player.
offensive_two_point_field_goals_attempted	double	The number of 2-point field goals attempted for a team or player.
offensive_avg_two_point_field_goals_made	double	The number of 2-point field goals made per game for a team or player.
offensive_avg_two_point_field_goals_attempted	double	The number of 2-point field goals attempted per game for a team or player.
offensive_two_point_field_goal_pct	double	The percentage of 2-points fields goals made by a team or player.
offensive_shooting_efficiency	double	The efficiency with which a team or player shoots the basketball.
offensive_scoring_efficiency	double	The efficiency with which a team or player scores the basketball.
team_id	integer	Unique team identifier.
team_uid	character	ESPN universal team identifier (UID format 's:40~l:...~t:...').
team_guid	character	ESPN team GUID.
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 '#').
team_is_active	logical	TRUE if the team is currently active.
team_logo_href	character	Default team logo URL; team_detail = TRUE only.

Example

from sportsdataverse.mbb import espn_mbb_player_stats
df = espn_mbb_player_stats(athlete_id=4395624, season=2023)
df.select(["full_name", "team_display_name", "offensive_points"])

espn_mbb_schedule(dates=None, groups=50, season_type=None, limit=500, return_as_pandas=False, **kwargs) -> 'pl.DataFrame'

espn_mbb_schedule - look up the men's college basketball scheduler for a given season

Parameters

Parameter	Type	Default	Description
dates	int	None	Used to define different seasons. 2002 is the earliest available season.
groups	int	50	Used to define different divisions. 50 is Division I, 51 is Division II/Division III.
season_type	int	None	2 for regular season, 3 for post-season, 4 for off-season.
limit	int	500	number of records to return, default: 500.
return_as_pandas	bool	False	If True, returns a pandas dataframe. If False, returns a polars dataframe.

Returns

Polars dataframe containing schedule dates for the requested season. Returns None if no games

col_name	type	description
id	character	Id.
uid	character	ESPN UID string.
date	character	Date in YYYY-MM-DD format.
attendance	integer	Reported attendance.
time_valid	logical	Time valid.
neutral_site	logical	Neutral site.
conference_competition	logical	Conference competition.
play_by_play_available	logical	Whether play-by-play data is available.
recent	logical	Recent.
tournament_id	integer	ESPN tournament identifier.
start_date	character	Start date (YYYY-MM-DD).
broadcast	character	Broadcast information string.
highlights	integer	Game highlight urls.
notes_type	character	Notes type.
notes_headline	character	Notes headline.
broadcast_market	character	Broadcast market label (e.g. 'national', 'home').
broadcast_name	character	Broadcast name.
type_id	character	Type identifier (numeric).
type_abbreviation	character	Type abbreviation.
venue_id	character	Unique venue identifier.
venue_full_name	character	Venue full name.
venue_address_city	character	Venue address city.
venue_address_state	character	Venue address state / region.
venue_indoor	logical	TRUE if the venue is indoors.
status_clock	double	Status clock.
status_display_clock	character	Status display clock.
status_period	integer	Status period.
status_type_id	character	Unique identifier for status type.
status_type_name	character	Status type name.
status_type_state	character	Status type state.
status_type_completed	logical	Status type completed.
status_type_description	character	Status type description.
status_type_detail	character	Status type detail.
status_type_short_detail	character	Status type short detail.
format_regulation_periods	integer	Format regulation periods.
home_id	character	Unique identifier for home.
home_uid	character	Home team's uid.
home_location	character	Home team's location.
home_name	character	Home name.
home_abbreviation	character	Home team's abbreviation.
home_display_name	character	Home display name.
home_short_display_name	character	Home short display name.
home_color	character	Color code (hex) for home.
home_alternate_color	character	Color code (hex) for home alternate.
home_is_active	logical	Home team's is active.
home_venue_id	character	Unique identifier for home venue.
home_logo	character	Home team logo URL.
home_conference_id	character	Unique identifier for home conference.
home_score	character	Home team score at the time of the play.
home_winner	logical	Home team's winner.
home_current_rank	integer
home_linescores	integer
home_records	character
away_id	character	Unique identifier for away.
away_uid	character	Away team's uid.
away_location	character	Away team's location.
away_name	character	Away name.
away_abbreviation	character	Away team's abbreviation.
away_display_name	character	Away display name.
away_short_display_name	character	Away short display name.
away_color	character	Color code (hex) for away.
away_alternate_color	character	Color code (hex) for away alternate.
away_is_active	logical	Away team's is active.
away_venue_id	character	Unique identifier for away venue.
away_logo	character	Away team logo URL.
away_conference_id	character	Unique identifier for away conference.
away_score	character	Away team score at the time of the play.
away_winner	logical	Away team's winner.
away_current_rank	integer
away_linescores	integer
away_records	character
game_id	integer	Unique game identifier.
season	integer	Season year.
season_type	integer	Season type (1=pre-season, 2=regular season, 3=postseason, 4=off-season for ESPN; or string label for WNBA Stats).

Example

from sportsdataverse.mbb import espn_mbb_schedule
day = espn_mbb_schedule(dates=20240408)
print(day.shape)

# Season-level pull (2024 season)

season = espn_mbb_schedule(dates=2024, limit=1500)
print(season.shape)

# Filter to a specific team (Duke ``team_id=150``)

import polars as pl
duke = season.filter(
    (pl.col("home_id") == "150") | (pl.col("away_id") == "150")
)

# Pandas round-trip

season_pd = espn_mbb_schedule(dates=2024, return_as_pandas=True)
season_pd.head()

Utilities & helpers

most_recent_mbb_season()

Return the most recent men's college basketball season year.

The men's college basketball season spans early November through early April; for any month October-December the "current season" is the following calendar year (e.g. October 2025 returns 2026).

Returns

The most recent / current season year.

Example

from sportsdataverse.mbb import most_recent_mbb_season, espn_mbb_schedule
season = most_recent_mbb_season()
sched = espn_mbb_schedule(dates=season)

Other

espn_mbb_teams(groups=None, return_as_pandas=False, **kwargs) -> 'pl.DataFrame'

espn_mbb_teams - look up the men's college basketball teams

Parameters

Parameter	Type	Default	Description
groups	int	None	Used to define different divisions. 50 is Division I, 51 is Division II/Division III.
return_as_pandas	bool	False	If True, returns a pandas dataframe. If False, returns a polars dataframe.

Returns

Polars dataframe containing teams for the requested league. This function caches by default, so if you want to refresh the data, use the command sportsdataverse.mbb.espn_mbb_teams.clear_cache().

col_name	type	description
team_abbreviation	character	Short team abbreviation (e.g. 'LAS').
team_alternate_color	character	Team alternate color (hex without leading '#').
team_color	character	Team primary color (hex without leading '#').
team_display_name	character	Full team display name.
team_id	character	Unique team identifier.
team_is_active	logical	TRUE if the team is currently active.
team_is_all_star	logical	TRUE if the row represents an All-Star team.
team_location	character	Team city or location string.
team_logos	integer	Team logo metadata.
team_name	character	Full team display name (e.g. 'Las Vegas Aces').
team_nickname	character	Team nickname.
team_short_display_name	character	Short team display name (e.g. 'Aces').
team_slug	character	URL-safe team identifier (e.g. 'lasvegas-aces' / 'aces').
team_uid	character	ESPN universal team identifier (UID format 's:40~l:...~t:...').

Example

from sportsdataverse.mbb import espn_mbb_teams
teams = espn_mbb_teams()
print(teams.shape)
print(teams.columns[:8])

# Walk every team-id (handy for batched scrapes)

team_ids = teams["team_id"].to_list()
print(len(team_ids), "D1 teams")

# Pandas round-trip + Division II/III

d2_d3 = espn_mbb_teams(groups=51, return_as_pandas=True)
d2_d3.head()

mbb_pbp_disk(game_id, path_to_json)

No description available.

Parameters

Parameter	Type	Default	Description
game_id
path_to_json

scoreboard_event_parsing(event)

No description available.

Parameters

Parameter	Type	Default	Description
event