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
| 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 | Int64 | Unique athlete identifier (ESPN). |
athlete_display_name | String | Athlete display name (full). |
athlete_short_name | String | Athlete short display name. |
athlete_position | String | Athlete position. |
athlete_jersey | String | Athlete jersey number. |
athlete_team_id | Int64 | |
athlete_team_abbreviation | String | |
split_name | String | Split name (typically "All Splits"). |
split_category | String | |
games_played | String | Games played. |
avg_minutes | String | |
field_goal_pct | String | Field goal percentage (0-1). |
three_point_pct | String | |
free_throw_pct | String | Free throw percentage (0-1). |
avg_rebounds | String | |
avg_assists | String | |
avg_blocks | String | |
avg_steals | String | |
avg_fouls | String | |
avg_turnovers | String | |
avg_points | String |
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_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
| 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 | String | 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 | String | 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 | String | Category of a named split; null on the Web v3 per-season rows. |
split_value | String | Value of a named split; null on the Web v3 per-season rows. |
season | Int64 | Season end year of the row (e.g., 2011 for 2010-11); null on the "Career" row. |
team_id | Int64 | ESPN team id (Int64) the athlete played that season for; a traded player has one row per team. Null on the "Career" row. |
position | String | Position abbreviation the athlete was listed at for that season and team (e.g., "G"); null on the "Career" row. |
games_played | String | Games played (GP), as ESPN ships it (a string). |
games_started | String | Games started (GS). |
avg_minutes | String | Minutes per game (MIN). |
avg_field_goals_made_avg_field_goals_attempted | String | Field goals made-attempted per game (FG), one "made-attempted" string (e.g., "3.9-9.0"). |
field_goal_pct | String | Field goal percentage (FG%), FGM / FGA x 100. |
avg_three_point_field_goals_made_avg_three_point_field_goals_attempted | String | Three-point field goals made-attempted per game (3PT), one "made-attempted" string. |
three_point_field_goal_pct | String | Three-point field goal percentage (3P%), 3PM / 3PA x 100. |
avg_free_throws_made_avg_free_throws_attempted | String | Free throws made-attempted per game (FT), one "made-attempted" string. |
free_throw_pct | String | Free throw percentage (FT%), FTM / FTA x 100. |
avg_offensive_rebounds | String | Offensive rebounds per game (OR). |
avg_defensive_rebounds | String | Defensive rebounds per game (DR). |
avg_rebounds | String | Rebounds per game (REB). |
avg_assists | String | Assists per game (AST). |
avg_blocks | String | Blocks per game (BLK). |
avg_steals | String | Steals per game (STL). |
avg_fouls | String | Personal fouls per game (PF). |
avg_turnovers | String | Turnovers per game (TO). |
avg_points | String | Points per game (PTS). |
field_goals_made_field_goals_attempted | String | Season field goals made-attempted (FG), one "made-attempted" string. |
three_point_field_goals_made_three_point_field_goals_attempted | String | Season three-point field goals made-attempted (3PT), one "made-attempted" string. |
free_throws_made_free_throws_attempted | String | Season free throws made-attempted (FT), one "made-attempted" string. |
offensive_rebounds | String | Season offensive rebounds (OR). |
defensive_rebounds | String | Season defensive rebounds (DR). |
total_rebounds | String | Season rebounds (REB). |
assists | String | Season assists (AST). |
blocks | String | Season blocked shots (BLK). |
steals | String | Season steals (STL). |
fouls | String | Season personal fouls (PF). |
turnovers | String | Season turnovers (TO). |
points | String | Season points (PTS). |
double_double | String | Games with double figures in two of points, rebounds, assists, steals and blocks (DD2). |
triple_double | String | Games with double figures in three of points, rebounds, assists, steals and blocks (TD3). |
disqualifications | String | Times the athlete fouled out (DQ). |
ejections | String | Times the athlete was ejected (EJECT). |
technical_fouls | String | Technical fouls called on the athlete (TECH). |
flagrant_fouls | String | Flagrant fouls called on the athlete (FLAG). |
assist_turnover_ratio | String | Assists per turnover (AST/TO). |
steal_turnover_ratio | String | Steals per turnover (STL/TO). |
rating | String | Player rating (RAT) as ESPN publishes it for college basketball. |
scoring_efficiency | String | ESPN's scoring efficiency (SC-EFF). |
shooting_efficiency | String | 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_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
| 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 | Int64 | ESPN season type of the row (2 regular season, 3 postseason). |
season_type_name | String | Season type's name as ESPN ships it (e.g., "2019-20 Regular Season"). |
category | String | Split the row was listed under; on the Web v3 payload a month (e.g., "january"). |
event_id | Int64 | ESPN event (game) id (Int64), the key the game endpoints take. |
event_date | String | Scheduled game start, ISO 8601 UTC as ESPN ships it. |
home_away | String | The athlete's side, "home" or "away", from which side the opponent was on; null when ESPN names neither. |
score | String | Final score as ESPN prints it, winner first (e.g., "123-115"). |
opponent_id | Int64 | ESPN team id (Int64) of the opponent. |
opponent_abbreviation | String | Opponent's abbreviation (e.g., "BOS"). |
opponent_display_name | String | Opponent's full name (e.g., "Boston Celtics"). |
game_result | String | The athlete's team result, "W" or "L" (or "T"). |
game_processed | String | Whether ESPN has finished processing the game's stats. |
minutes | String | Minutes 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_attempted | String | Field goals made-attempted, a "made-attempted" string (e.g., "1-4"). |
field_goal_pct | String | Field-goal percentage on a 0-100 scale, as a string (e.g., "25.0"). |
three_point_field_goals_made_three_point_field_goals_attempted | String | Three-pointers made-attempted, a "made-attempted" string (e.g., "0-2"). |
three_point_pct | String | Three-point percentage on a 0-100 scale, as a string. |
free_throws_made_free_throws_attempted | String | Free throws made-attempted, a "made-attempted" string. |
free_throw_pct | String | Free-throw percentage on a 0-100 scale, as a string. |
total_rebounds | String | Total rebounds in the game. |
assists | String | Assists in the game. |
blocks | String | Blocked shots in the game. |
steals | String | Steals in the game. |
fouls | String | Personal fouls in the game. |
turnovers | String | Turnovers in the game. |
points | String | Points the athlete scored in the game. |
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_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
| 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 | String | |
display_name | String | Display name. |
display_names | String | |
filters | String | |
labels | String | |
names | String | Names. |
split_categories | String |
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_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
| 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 | Int64 | 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 | Int64 | ESPN id of the athlete, the key the athlete endpoints (athlete_overview, athlete_stats) take. |
athlete_uid | String | ESPN composite athlete uid (s:<sport>~l:<league>~a:<athlete id>), kept as text. |
athlete_display_name | String | Athlete's full display name. |
athlete_short_name | String | Athlete's abbreviated name (e.g. 'B. Nix'). |
athlete_first_name | String | Athlete's first name. |
athlete_last_name | String | Athlete's last name. |
athlete_position | String | Athlete's position abbreviation (e.g. QB, G, C). |
athlete_status | String | Athlete's ESPN status name (e.g. Active, Inactive) as ESPN reports it at request time, not for the requested season. |
team_id | Int64 | ESPN id of the team the athlete played for in the requested season. |
team_abbreviation | String | Abbreviation of the athlete's team in the requested season (ESPN teamShortName, e.g. ORE). |
team_name | String | Nickname of the athlete's team in the requested season (ESPN teamName, e.g. Ducks). |
general_games_played | Float64 | Games Played (ESPN 'general' category). |
general_avg_minutes | Float64 | Minutes Per Game (ESPN 'general' category): The average number of minutes per game. |
general_avg_fouls | Float64 | Fouls Per Game (ESPN 'general' category): The average fouls committed per game. |
general_flagrant_fouls | Float64 | Flagrant Fouls (ESPN 'general' category): The number of fouls that the officials thought were unnecessary or excessive. |
general_technical_fouls | Float64 | 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 | Float64 | 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 | Float64 | 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 | Float64 | 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_per | Float64 | Player 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_minutes | Float64 | Minutes (ESPN 'general' category): The total number of minutes played. |
general_rebounds | Float64 | Rebounds (ESPN 'general' category): The total number of rebounds (offensive and defensive). |
general_fouls | Float64 | Fouls (ESPN 'general' category): The number of times a player had illegal contact with the opponent. |
general_avg_rebounds | Float64 | Rebounds Per Game (ESPN 'general' category): The average rebounds per game. |
offensive_avg_points | Float64 | Points Per Game (ESPN 'offensive' category): The average number of points scored per game. |
offensive_avg_field_goals_made | Float64 | Average Field Goals Made (ESPN 'offensive' category): The average field goals made per game. |
offensive_avg_field_goals_attempted | Float64 | Average Field Goals Attempted (ESPN 'offensive' category): The average field goals attempted per game. |
offensive_field_goal_pct | Float64 | 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 | Float64 | 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 | Float64 | Average 3-Point Field Goals Attempted (ESPN 'offensive' category): The average three point field goals attempted per game. |
offensive_three_point_field_goal_pct | Float64 | 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 | Float64 | Average Free Throws Made (ESPN 'offensive' category): The average free throw shots made per game. |
offensive_avg_free_throws_attempted | Float64 | Average Free Throws Attempted (ESPN 'offensive' category): The average free throw shots attempted per game. |
offensive_free_throw_pct | Float64 | Free Throw Percentage (ESPN 'offensive' category): The ratio of free throws made to free throws attempted: FTM / FTA. |
offensive_avg_assists | Float64 | Assists Per Game (ESPN 'offensive' category): The average assists per game. |
offensive_avg_turnovers | Float64 | Turnovers Per Game (ESPN 'offensive' category): The average turnovers committed per game. |
offensive_points | Float64 | Points (ESPN 'Points', offensive category): points scored in basketball; goals plus assists in hockey. |
offensive_field_goals_made | Float64 | Field Goals Made (ESPN 'offensive' category): The number of times a 2pt field goal was made. |
offensive_field_goals_attempted | Float64 | Field Goals Attempted (ESPN 'offensive' category): The number of times a 2pt field goal was attempted. |
offensive_three_point_field_goals_made | Float64 | 3-Point Field Goals Made (ESPN 'offensive' category): The number of times a 3pt field goal was made. |
offensive_three_point_field_goals_attempted | Float64 | 3-Point Field Goals Attempted (ESPN 'offensive' category): The number of times a 3pt field goal was attempted. |
offensive_free_throws_made | Float64 | Free Throws Made (ESPN 'offensive' category): The number of times a free throw was made. |
offensive_free_throws_attempted | Float64 | Free Throws Attempted (ESPN 'offensive' category): The number of times a free throw was attempted. |
offensive_assists | Float64 | Assists (ESPN 'Assists', offensive category): passes that lead directly to a score in basketball; goal assists in hockey. |
offensive_turnovers | Float64 | Turnovers (ESPN 'offensive' category): The number of times a player loses possession to the other team. |
defensive_avg_steals | Float64 | Steals Per Game (ESPN 'defensive' category): The average steals per game. |
defensive_avg_blocks | Float64 | Blocks Per Game (ESPN 'defensive' category): The average blocks per game. |
defensive_steals | Float64 | 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 | Float64 | 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_mbb_leaders()