Skip to main content

Men's college basketball — ESPN web API (v3)

sportsdataverse.mbb — 5 endpoints.

espn_mbb_player_overview​

ESPN endpoint.

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

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

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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_nametypedescription
athlete_idInt64Unique athlete identifier (ESPN).
athlete_display_nameStringAthlete display name (full).
athlete_short_nameStringAthlete short display name.
athlete_positionStringAthlete position.
athlete_jerseyStringAthlete jersey number.
athlete_team_idInt64
athlete_team_abbreviationString
split_nameStringSplit name (typically "All Splits").
split_categoryString
games_playedStringGames played.
avg_minutesString
field_goal_pctStringField goal percentage (0-1).
three_point_pctString
free_throw_pctStringFree throw percentage (0-1).
avg_reboundsString
avg_assistsString
avg_blocksString
avg_stealsString
avg_foulsString
avg_turnoversString
avg_pointsString

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.

Example​

espn_mbb_player_overview(athlete_id='4239')

espn_mbb_player_stats_v3​

ESPN endpoint.

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

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/basketball/mens-college-basketball/athletes/4684793/stats

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_id path parameter.
seasonseasonYSeason 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_nametypedescription
categoryStringESPN 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_nameStringSeason 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_categoryStringCategory of a named split; null on the Web v3 per-season rows.
split_valueStringValue of a named split; null on the Web v3 per-season rows.
seasonInt64Season end year of the row (e.g., 2011 for 2010-11); null on the "Career" row.
team_idInt64ESPN team id (Int64) the athlete played that season for; a traded player has one row per team. Null on the "Career" row.
positionStringPosition abbreviation the athlete was listed at for that season and team (e.g., "G"); null on the "Career" row.
games_playedStringGames played (GP), as ESPN ships it (a string).
games_startedStringGames started (GS).
avg_minutesStringMinutes per game (MIN).
avg_field_goals_made_avg_field_goals_attemptedStringField goals made-attempted per game (FG), one "made-attempted" string (e.g., "3.9-9.0").
field_goal_pctStringField goal percentage (FG%), FGM / FGA x 100.
avg_three_point_field_goals_made_avg_three_point_field_goals_attemptedStringThree-point field goals made-attempted per game (3PT), one "made-attempted" string.
three_point_field_goal_pctStringThree-point field goal percentage (3P%), 3PM / 3PA x 100.
avg_free_throws_made_avg_free_throws_attemptedStringFree throws made-attempted per game (FT), one "made-attempted" string.
free_throw_pctStringFree throw percentage (FT%), FTM / FTA x 100.
avg_offensive_reboundsStringOffensive rebounds per game (OR).
avg_defensive_reboundsStringDefensive rebounds per game (DR).
avg_reboundsStringRebounds per game (REB).
avg_assistsStringAssists per game (AST).
avg_blocksStringBlocks per game (BLK).
avg_stealsStringSteals per game (STL).
avg_foulsStringPersonal fouls per game (PF).
avg_turnoversStringTurnovers per game (TO).
avg_pointsStringPoints per game (PTS).
field_goals_made_field_goals_attemptedStringSeason field goals made-attempted (FG), one "made-attempted" string.
three_point_field_goals_made_three_point_field_goals_attemptedStringSeason three-point field goals made-attempted (3PT), one "made-attempted" string.
free_throws_made_free_throws_attemptedStringSeason free throws made-attempted (FT), one "made-attempted" string.
offensive_reboundsStringSeason offensive rebounds (OR).
defensive_reboundsStringSeason defensive rebounds (DR).
total_reboundsStringSeason rebounds (REB).
assistsStringSeason assists (AST).
blocksStringSeason blocked shots (BLK).
stealsStringSeason steals (STL).
foulsStringSeason personal fouls (PF).
turnoversStringSeason turnovers (TO).
pointsStringSeason points (PTS).
double_doubleStringGames with double figures in two of points, rebounds, assists, steals and blocks (DD2).
triple_doubleStringGames with double figures in three of points, rebounds, assists, steals and blocks (TD3).
disqualificationsStringTimes the athlete fouled out (DQ).
ejectionsStringTimes the athlete was ejected (EJECT).
technical_foulsStringTechnical fouls called on the athlete (TECH).
flagrant_foulsStringFlagrant fouls called on the athlete (FLAG).
assist_turnover_ratioStringAssists per turnover (AST/TO).
steal_turnover_ratioStringSteals per turnover (STL/TO).
ratingStringPlayer rating (RAT) as ESPN publishes it for college basketball.
scoring_efficiencyStringESPN's scoring efficiency (SC-EFF).
shooting_efficiencyStringESPN's shooting efficiency (SH-EFF).

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.

Example​

espn_mbb_player_stats_v3(athlete_id='4684793')

espn_mbb_player_gamelog​

ESPN endpoint.

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

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

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_id path parameter.
seasonseasonYSeason 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_nametypedescription
season_type_idInt64ESPN season type of the row (2 regular season, 3 postseason).
season_type_nameStringSeason type's name as ESPN ships it (e.g., "2019-20 Regular Season").
categoryStringSplit the row was listed under; on the Web v3 payload a month (e.g., "january").
event_idInt64ESPN event (game) id (Int64), the key the game endpoints take.
event_dateStringScheduled game start, ISO 8601 UTC as ESPN ships it.
home_awayStringThe athlete's side, "home" or "away", from which side the opponent was on; null when ESPN names neither.
scoreStringFinal score as ESPN prints it, winner first (e.g., "123-115").
opponent_idInt64ESPN team id (Int64) of the opponent.
opponent_abbreviationStringOpponent's abbreviation (e.g., "BOS").
opponent_display_nameStringOpponent's full name (e.g., "Boston Celtics").
game_resultStringThe athlete's team result, "W" or "L" (or "T").
game_processedStringWhether ESPN has finished processing the game's stats.
minutesStringMinutes played, a whole-number string as ESPN ships it (e.g., "21"). The stat columns from here on are named from the payload's own stat names, so they differ by sport, and every value is a string.
field_goals_made_field_goals_attemptedStringField goals made-attempted, a "made-attempted" string (e.g., "1-4").
field_goal_pctStringField-goal percentage on a 0-100 scale, as a string (e.g., "25.0").
three_point_field_goals_made_three_point_field_goals_attemptedStringThree-pointers made-attempted, a "made-attempted" string (e.g., "0-2").
three_point_pctStringThree-point percentage on a 0-100 scale, as a string.
free_throws_made_free_throws_attemptedStringFree throws made-attempted, a "made-attempted" string.
free_throw_pctStringFree-throw percentage on a 0-100 scale, as a string.
total_reboundsStringTotal rebounds in the game.
assistsStringAssists in the game.
blocksStringBlocked shots in the game.
stealsStringSteals in the game.
foulsStringPersonal fouls in the game.
turnoversStringTurnovers in the game.
pointsStringPoints the athlete scored in the game.

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.

Example​

espn_mbb_player_gamelog(athlete_id='4239')

espn_mbb_player_splits​

ESPN endpoint.

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

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

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_id path parameter.
seasonseasonYSeason 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_nametypedescription
descriptionsString
display_nameStringDisplay name.
display_namesString
filtersString
labelsString
namesStringNames.
split_categoriesString

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.

Example​

espn_mbb_player_splits(athlete_id='4239')

espn_mbb_leaders​

ESPN endpoint.

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

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

API ParameterPythonPatternRequiredNullableDescription
categorycategoryYLeaderboard 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).
seasonseasonYSeason year (e.g. 2024).
seasontypeseason_typeYSeason phase: 1=preseason, 2=regular season, 3=postseason.
limitlimitYMaximum number of items to return.
pagepageYpage query parameter.
sortsortYSort 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_nametypedescription
sort_orderInt64Position 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_idInt64ESPN id of the athlete, the key the athlete endpoints (athlete_overview, athlete_stats) take.
athlete_uidStringESPN composite athlete uid (s:<sport>~l:<league>~a:<athlete id>), kept as text.
athlete_display_nameStringAthlete's full display name.
athlete_short_nameStringAthlete's abbreviated name (e.g. 'B. Nix').
athlete_first_nameStringAthlete's first name.
athlete_last_nameStringAthlete's last name.
athlete_positionStringAthlete's position abbreviation (e.g. QB, G, C).
athlete_statusStringAthlete's ESPN status name (e.g. Active, Inactive) as ESPN reports it at request time, not for the requested season.
team_idInt64ESPN id of the team the athlete played for in the requested season.
team_abbreviationStringAbbreviation of the athlete's team in the requested season (ESPN teamShortName, e.g. ORE).
team_nameStringNickname of the athlete's team in the requested season (ESPN teamName, e.g. Ducks).
general_games_playedFloat64Games Played (ESPN 'general' category).
general_avg_minutesFloat64Minutes Per Game (ESPN 'general' category): The average number of minutes per game.
general_avg_foulsFloat64Fouls Per Game (ESPN 'general' category): The average fouls committed per game.
general_flagrant_foulsFloat64Flagrant Fouls (ESPN 'general' category): The number of fouls that the officials thought were unnecessary or excessive.
general_technical_foulsFloat64Technical Fouls (ESPN 'general' category): The number of times an player or coach was called for a technical foul (unsportsmanlike conduct or violations).
general_ejectionsFloat64Ejections (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_doubleFloat64Double 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_doubleFloat64Triple 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_perFloat64Player Efficiency Rating (ESPN 'general' category): 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_minutesFloat64Minutes (ESPN 'general' category): The total number of minutes played.
general_reboundsFloat64Rebounds (ESPN 'general' category): The total number of rebounds (offensive and defensive).
general_foulsFloat64Fouls (ESPN 'general' category): The number of times a player had illegal contact with the opponent.
general_avg_reboundsFloat64Rebounds Per Game (ESPN 'general' category): The average rebounds per game.
offensive_avg_pointsFloat64Points Per Game (ESPN 'offensive' category): The average number of points scored per game.
offensive_avg_field_goals_madeFloat64Average Field Goals Made (ESPN 'offensive' category): The average field goals made per game.
offensive_avg_field_goals_attemptedFloat64Average Field Goals Attempted (ESPN 'offensive' category): The average field goals attempted per game.
offensive_field_goal_pctFloat64Field Goal Percentage (ESPN 'offensive' category): The ratio of field goals made to field goals attempted: FGM / FGA.
offensive_avg_three_point_field_goals_madeFloat64Average 3-Point Field Goals Made (ESPN 'offensive' category): The average three point field goals made per game.
offensive_avg_three_point_field_goals_attemptedFloat64Average 3-Point Field Goals Attempted (ESPN 'offensive' category): The average three point field goals attempted per game.
offensive_three_point_field_goal_pctFloat643-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_madeFloat64Average Free Throws Made (ESPN 'offensive' category): The average free throw shots made per game.
offensive_avg_free_throws_attemptedFloat64Average Free Throws Attempted (ESPN 'offensive' category): The average free throw shots attempted per game.
offensive_free_throw_pctFloat64Free Throw Percentage (ESPN 'offensive' category): The ratio of free throws made to free throws attempted: FTM / FTA.
offensive_avg_assistsFloat64Assists Per Game (ESPN 'offensive' category): The average assists per game.
offensive_avg_turnoversFloat64Turnovers Per Game (ESPN 'offensive' category): The average turnovers committed per game.
offensive_pointsFloat64Points (ESPN 'Points', offensive category): points scored in basketball; goals plus assists in hockey.
offensive_field_goals_madeFloat64Field Goals Made (ESPN 'offensive' category): The number of times a 2pt field goal was made.
offensive_field_goals_attemptedFloat64Field Goals Attempted (ESPN 'offensive' category): The number of times a 2pt field goal was attempted.
offensive_three_point_field_goals_madeFloat643-Point Field Goals Made (ESPN 'offensive' category): The number of times a 3pt field goal was made.
offensive_three_point_field_goals_attemptedFloat643-Point Field Goals Attempted (ESPN 'offensive' category): The number of times a 3pt field goal was attempted.
offensive_free_throws_madeFloat64Free Throws Made (ESPN 'offensive' category): The number of times a free throw was made.
offensive_free_throws_attemptedFloat64Free Throws Attempted (ESPN 'offensive' category): The number of times a free throw was attempted.
offensive_assistsFloat64Assists (ESPN 'Assists', offensive category): passes that lead directly to a score in basketball; goal assists in hockey.
offensive_turnoversFloat64Turnovers (ESPN 'offensive' category): The number of times a player loses possession to the other team.
defensive_avg_stealsFloat64Steals Per Game (ESPN 'defensive' category): The average steals per game.
defensive_avg_blocksFloat64Blocks Per Game (ESPN 'defensive' category): The average blocks per game.
defensive_stealsFloat64Steals (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_blocksFloat64Blocks (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​

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.

Example​

espn_mbb_leaders()