CFB — ESPN site API (v2) — Other

espn_cfb_scoreboard

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20240115&limit=500

API Parameter	Python	Pattern	Required	Nullable	Description
dates	dates			Y	Date or date range filter (YYYYMMDD or YYYYMMDD-YYYYMMDD).
week	week			Y	Week number within the season.
seasontype	season_type			Y	Season phase: 1=preseason, 2=regular season, 3=postseason.
groups	groups			Y	Conference or group id filter (e.g. an ESPN conference id).
limit	limit			Y	Maximum number of items to return.

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
game_id	integer	ESPN event id.
uid	character	ESPN global unique identifier.
date	character	Match start timestamp (ISO 8601, UTC).
name	character	Full event name (e.g. 'Team A at Team B').
short_name	character	Abbreviated event name (e.g. 'TA @ TB').
season_year	integer	Integer season year ESPN assigns the event (e.g. 2025 for the 2025-26 season).
season_type	integer	ESPN season-type id of the event's season: 1 preseason, 2 regular season, 3 postseason, 4 offseason for the US leagues; soccer competitions carry their own competition-specific ids (e.g. 13481).
season_slug	character	ESPN slug of the event's season type (e.g. 'regular-season', 'post-season'; soccer competitions use their own, such as 'final' or 'torneo-apertura').
status_type_id	integer
status_type_name	character
status_type_state	character
status_type_completed	logical
status_type_description	character
status_type_detail	character
status_type_short_detail	character
status_clock	double	Game clock in seconds as ESPN reports it: time remaining in the period for clock sports, elapsed seconds for soccer (e.g. 5400.0 at full time); 0.0 once a game has ended.
status_display_clock	character
status_period	integer	Current or final period number (quarter, half, inning or period, depending on the sport).
neutral_site	logical	Whether the match is played at a neutral venue.
conference_competition	logical
attendance	integer	Reported attendance at the game.
venue_id	integer	Referencing venue id.
venue_full_name	character
venue_city	character	City where the venue is located.
venue_state	character	State (or province/country) where the venue is located.
venue_indoor	logical	Whether the home venue is indoors.
broadcast	character	Every network name of the competition in feed order, deduped and ", "-joined (an entry with no names gives its market); "" when the game lists no broadcast.
note	character	Event note text from the competition (e.g. a series or game label such as 'World Series - Game 1', or a shootout result); an empty string when there is none.
home_id	integer	Home team referencing id.
home_name	character
home_abbreviation	character
home_display_name	character
home_location	character
home_color	character
home_alternate_color	character
home_logo	character
home_score	character	Home team's score. For cricket, the innings string (e.g. '161/5 (18/20 ov, target 156)').
home_winner	logical
home_rank	integer
away_id	integer	Away team referencing id.
away_name	character
away_abbreviation	character
away_display_name	character
away_location	character
away_color	character
away_alternate_color	character
away_logo	character
away_score	character	Away team's score. For cricket, the innings string.
away_winner	logical
away_rank	integer

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_cfb_scoreboard(dates='20240115')

espn_cfb_summary

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/summary

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/summary

API Parameter	Python	Pattern	Required	Nullable	Description
event	event_id			Y	event query parameter.

Returns

return_parsed=True (default) — a dict of polars.DataFrames keyed by summary section (one table per documented key below); pass return_as_pandas=True for a dict of pandas.DataFrames (same keys).

boxscore_player

col_name	type	description
team_id	integer	Team id.
team_abbreviation	character	Team abbreviation.
team_display_name	character	Team display name.
team_location	character	Team location.
athlete_id	integer	Athlete id.
athlete_display_name	character	Athlete display name.
athlete_short_name	character	Athlete short name.
athlete_jersey	character	Athlete jersey.
athlete_position	character	Athlete position.
starter	character	Starter.
active	character	Active.
did_not_play	character	Did not play.
ejected	character	Ejected.
reason	character	Reason.
completions/passing_attempts	character	Pass completion ratio for the player in the box score, expressed as completions divided by pass attempts.
passing_yards	character
yards_per_pass_attempt	character	Average passing yards gained per pass attempt by the player in the box score.
passing_touchdowns	character	Number of touchdown passes thrown by the player in the box score.
interceptions	character	Passing interceptions.
adj_qbr	character	ESPN's Adjusted Quarterback Rating for the player, measuring overall passing efficiency on a 0-100 scale.
rushing_attempts	character	Team rushing attempts.
rushing_yards	character	Team rushing yards.
yards_per_rush_attempt	character	Team yards per rush attempt.
rushing_touchdowns	character	Number of rushing touchdowns scored by the player in the box score.
long_rushing	character	Longest single rushing gain recorded by the player in the game.
receptions	character
receiving_yards	character
yards_per_reception	character	Average receiving yards gained per reception by the player in the box score.
receiving_touchdowns	character	Number of receiving touchdowns scored by the player in the box score.
long_reception	character	Longest single reception recorded by the player in the game.
fumbles	character	Number of fumbles committed by the player in the box score.
fumbles_lost	character	Fumbles lost.
fumbles_recovered	character	Team fumbles recovered.
total_tackles	character	Total tackles recorded by the player, including both solo and assisted tackles.
solo_tackles	character	Number of unassisted tackles recorded by the player in the box score.
sacks	character	Team sacks.
tackles_for_loss	character	Team tackles for a loss.
passes_defended	character	Number of pass plays disrupted or broken up by the defensive player in the game.
hurries	character	Number of times the player pressured the opposing passer into an early or errant throw.
defensive_touchdowns	character	Number of touchdowns scored by the player via defensive plays such as interception or fumble returns.
kick_returns	character	Number of kick returns.
kick_return_yards	character	Team kick return yards.
yards_per_kick_return	character	Average yards gained per kick return by the player in the box score.
long_kick_return	character	Longest single kick return yardage recorded by the player in the game.
kick_return_touchdowns	character	Number of touchdowns scored on kick returns by the player in the box score.
punt_returns	character	Number of punt returns.
punt_return_yards	character	Team punt return yards.
yards_per_punt_return	character	Average yards gained per punt return by the player in the box score.
long_punt_return	character	Longest single punt return yardage recorded by the player in the game.
punt_return_touchdowns	character	Number of touchdowns scored on punt returns by the player in the box score.
field_goals_made/field_goal_attempts	character	Field goal conversion ratio for the player, expressed as field goals made divided by attempts.
field_goal_pct	character
long_field_goal_made	character	Distance of the longest successful field goal kicked by the player in the game.
extra_points_made/extra_point_attempts	character	Extra point conversion ratio for the player, expressed as extra points made divided by attempts.
total_kicking_points	character	Total points contributed by the player through field goals and extra points in the game.
punts	character	Total number of punts executed by the player in the box score.
punt_yards	character	Total yardage of all punts executed by the player in the game.
gross_avg_punt_yards	character	Average gross punt distance before accounting for returns, recorded for the player in the game.
touchbacks	character	Number of punts or kick-offs by the player that resulted in the opposing team starting from their own end zone.
punts_inside20	character	Number of punts by the player that were downed or stopped inside the opposing team's 20-yard line.
long_punt	character	Distance of the longest individual punt executed by the player in the game.

boxscore_team

col_name	type	description
team_id	integer	Team id.
team_abbreviation	character	Team abbreviation.
team_display_name	character	Team display name.
home_away	character	Home away.
display_order	integer	Display order.
stat_name	character	Stat name.
stat_label	character	Stat label.
stat_display_value	character	Stat display value.
stat_value	character	Stat value.

winprobability

col_name	type	description
home_win_percentage	double	Home win percentage.
tie_percentage	double	Tie percentage.
play_id	integer	Play id.

leaders

col_name	type	description
team_id	integer	Team id.
team_abbreviation	character	Team abbreviation.
category_name	character	Category name.
category_display_name	character	Category display name.
athlete_id	integer	Athlete id.
athlete_display_name	character	Athlete display name.
athlete_position	character	Athlete position.
value	double	Value.
display_value	character	Display value.
main_stat	character	Main stat.
summary	character	Summary.

game_info

col_name	type	description
attendance	integer	Attendance.
venue_id	integer	Venue id.
venue_guid	character	Venue guid.
venue_full_name	character	Venue full name.
venue_address_city	character	Venue address city.
venue_address_state	character	Venue address state.
venue_address_zip_code	character	Postal zip code of the venue where the game was played.
venue_address_country	character	Country of the venue where the game was played.
venue_grass	logical	Venue grass.

header

col_name	type	description
id	integer	Id.
uid	character	Uid.
time_valid	logical	Time valid.
competitions	character	Competitions.
links	character	Links.
week	integer	Game week of the season.
game_note	character	Optional editorial note or context annotation attached to the game in the header.
season_year	integer	Season year.
season_current	logical	Season current.
season_type	integer	Season type.
league_id	integer	League id.
league_uid	character	League uid.
league_name	character	League name.
league_abbreviation	character	League abbreviation.
league_midsize_name	character	Medium-length display name for the league or competition as shown in the game header.
league_slug	character	League slug.
league_is_tournament	logical	League is tournament.
league_links	character	League links.
league_logos	character	League logos.

standings

col_name	type	description
group_header	character	Group header.
conference_header	character	Conference header.
division_header	character	Division header.
team_id	integer	Team id.
team_uid	character	Team uid.
team_location	character	Team location.
overall	character	Overall draft pick number.
vs. conf.	character	Team's record against conference opponents, shown as part of the standings snapshot in the box score.

broadcasts

col_name	type	description
station	character	Broadcast station / network name (e.g. ESPN+).
station_key	character	Machine-readable key identifying the broadcasting station airing the game.
lang	character	Broadcast language code.
region	character	Broadcast region code.
is_national	logical	Boolean flag indicating whether the broadcast is a nationally distributed feed.
type_id	integer	Type id.
type_short_name	character
type_long_name	character
type_slug	character	Broadcast-type slug (e.g. streaming, tv).
market_id	integer	ESPN futures-market identifier.
market_type	character	Geographic market type (e.g. National).
media_call_letters	character	Broadcast call letters for the outlet.
media_name	character	ESPN media name for the outlet.
media_short_name	character	Short ESPN media name for the outlet.

format

col_name	type	description
regulation_periods	integer	Regulation periods.
regulation_display_name	character	Regulation display name.
regulation_slug	character	Regulation slug.
regulation_clock	double	Regulation clock.
overtime_display_name	character	Overtime display name.
overtime_slug	character	Overtime slug.
sudden_death_periods	integer	Number of sudden-death overtime periods defined in the game format rules.

article

col_name	type	description
id	integer	Id.
now_id	character	Now id.
content_key	character	Content key.
data_source_identifier	character	Data source identifier.
publishedkey	character	Publishedkey.
type	character	Type.
game_id	integer	Game id.
headline	character	Headline.
description	character	Description.
link_text	character	Link text.
categorized	character	Categorized.
originally_posted	character	Originally posted.
last_modified	character	Last modified.
published	character	Published.
section	character	Section.
source	character	Source.
images	character	Images.
video	character	Video.
categories	character	Categories.
keywords	character	Keywords.
story	character	Story.
premium	logical	Premium.
is_live_blog	logical	Is live blog.
allow_comments	logical	Allow comments.
allow_search	logical	Allow search.
allow_content_reactions	logical	Allow content reactions.
links_web_href	character	Links web href.
links_mobile_href	character	Links mobile href.
links_api_self_href	character	Links api self href.
links_app_sportscenter_href	character	Links app sportscenter href.

news

col_name	type	description
id	integer	Id.
now_id	character	Now id.
content_key	character	Content key.
data_source_identifier	character	Data source identifier.
type	character	Type.
headline	character	Headline.
description	character	Description.
last_modified	character	Last modified.
published	character	Published.
images	character	Images.
categories	character	Categories.
premium	logical	Premium.
links_web_href	character	Links web href.
links_web_self_href	character	URL for the canonical web page of the associated article or editorial content.
links_web_self_dsi_href	character	Data-source-identified URL for the web page of the associated article content.
links_api_self_href	character	Links api self href.
links_api_artwork_href	character	API endpoint URL for artwork or imagery associated with the article.
links_sportscenter_href	character	URL for the article's page on ESPN's SportsCenter platform.
byline	character	Byline.
links_mobile_href	character	Links mobile href.
links_app_sportscenter_href	character	Links app sportscenter href.

drives

col_name	type	description
id	integer	Id.
description	character	Description.
yards	integer	Total yards gained on the drive.
is_score	logical	TRUE if the drive resulted in a score.
offensive_plays	integer	Number of offensive plays on the drive.
result	character	Drive result code (e.g. PUNT, TD).
short_display_result	character	Short drive-result label.
display_result	character	Drive-result label (e.g. Punt, Touchdown).
plays	character	Total qualifying passing plays included in the WEPA calculation.
team_id	integer	Team id.
team_name	character	Full display name of the team.
team_abbreviation	character	Team abbreviation.
team_display_name	character	Team display name.
team_short_display_name	character	Short team display name.
team_logos	character	Team logos.
start_period_type	character	Period type at the start of the drive (e.g. quarter).
start_period_number	integer	Period or quarter number in which the drive or sequence began.
start_clock_display_value	character	Game clock time displayed at the start of the drive or scoring sequence.
start_yard_line	integer	Yard line at the start of the play.
start_text	character	Field-position text at the start of the drive.
end_period_type	character	Period type at the end of the drive (e.g. quarter).
end_period_number	integer	Period or quarter number in which the drive or sequence ended.
end_clock_display_value	character	Game clock time displayed at the end of the drive or scoring sequence.
end_yard_line	integer	Yard line at the end of the play.
end_text	character	Field-position text at the end of the drive.
time_elapsed_display_value	character	Human-readable duration of time elapsed during the drive or scoring sequence.

drive_plays

col_name	type	description
drive_id	integer	CFBD drive identifier the play belongs to.
drive_sequence	integer	Sequential position of the drive within the game's broadcast or play-by-play listing.
id	integer	Id.
sequence_number	character	Sequence number.
text	character	Text.
away_score	integer	Away score.
home_score	integer	Home score.
scoring_play	logical	Scoring play.
priority	logical	TRUE if ESPN flags the play as a priority highlight.
modified	character	ISO timestamp the play record was last modified.
wallclock	character	Wallclock.
team_participants	character	Teams or participants associated with a specific drive or sequence in the broadcast record.
is_penalty	logical	TRUE if the play was a penalty.
stat_yardage	integer	Yards gained or lost on the play.
is_turnover	logical	TRUE if the play was a turnover.
type_id	integer	Type id.
type_text	character	Type text.
type_abbreviation	character	Play-type abbreviation (e.g. RUSH, TD).
period_number	integer	Period number.
clock_display_value	character	Clock display value.
start_down	integer	Down at the start of the play.
start_distance	integer	Yards to go at the start of the play.
start_yard_line	integer	Yard line at the start of the play.
start_yards_to_endzone	integer	Yards to the end zone at the start of the play.
start_team_id	integer	ESPN team id in possession at the start of the play.
end_down	integer	Down at the end of the play.
end_distance	integer	Yards to go at the end of the play.
end_yard_line	integer	Yard line at the end of the play.
end_yards_to_endzone	integer	Yards to the end zone at the end of the play.
end_down_distance_text	character	Down-and-distance text at the end of the play.
end_short_down_distance_text	character	Short down-and-distance text at the end of the play.
end_possession_text	character	Field-position text at the end of the play.
end_team_id	integer	ESPN team id in possession at the end of the play.
start_down_distance_text	character	Down-and-distance text at the start of the play.
start_short_down_distance_text	character	Short down-and-distance text at the start of the play.
start_possession_text	character	Field-position text at the start of the play.
scoring_type_name	character	Scoring-type key on a scoring play (e.g. touchdown).
scoring_type_display_name	character	Human-readable scoring-type name.
scoring_type_abbreviation	character	Scoring-type abbreviation (e.g. TD, FG).
point_after_attempt_id	integer	Point-after-attempt id on a scoring play.
point_after_attempt_text	character	Point-after-attempt text (e.g. Extra Point Good).
point_after_attempt_abbreviation	character	Point-after-attempt abbreviation.
point_after_attempt_value	double	Points added by the point-after attempt.
media_id	integer	ESPN media id for the outlet.

scoring_plays

col_name	type	description
id	integer	Id.
text	character	Text.
away_score	integer	Away score.
home_score	integer	Home score.
type_id	integer	Type id.
type_text	character	Type text.
type_abbreviation	character	Play-type abbreviation (e.g. RUSH, TD).
period_number	integer	Period number.
clock_value	double
clock_display_value	character	Clock display value.
team_id	integer	Team id.
team_uid	character	Team uid.
team_display_name	character	Team display name.
team_abbreviation	character	Team abbreviation.
team_links	character	Team links.
team_logo	character	Team logo.
team_logos	character	Team logos.
scoring_type_name	character	Scoring-type key on a scoring play (e.g. touchdown).
scoring_type_display_name	character	Human-readable scoring-type name.
scoring_type_abbreviation	character	Scoring-type abbreviation (e.g. TD, FG).

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_cfb_summary()

espn_cfb_calendar_site

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/calendar

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/calendar

API Parameter	Python	Pattern	Required	Nullable	Description

Returns

return_parsed=True (default) — the output of parse_items; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: 404 in nba, nfl, mlb, nhl, wnba, cfb, mbb, wbb with the documented example arguments (2026-10-07).

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_cfb_calendar_site()

espn_cfb_news

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/news

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/news?limit=50

API Parameter	Python	Pattern	Required	Nullable	Description
limit	limit			Y	Maximum number of items to return.

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
id	integer	ESPN numeric identifier for the article.
now_id	character	ESPN 'now' feed id.
content_key	character	Internal content key.
data_source_identifier	character	Source-system identifier.
type	character	Article type (Story, Media, HeadlineNews, etc.).
headline	character	Article headline.
description	character	Article summary/description.
last_modified	character	Last-modified timestamp (ISO 8601).
published	character	Publish timestamp (ISO 8601).
images	character	Article images (list, stringified).
categories	character	Article categories (list, stringified).
premium	logical	Whether the article is premium/paywalled.
byline	character	Author byline string as published by ESPN.
links_web_href	character	Web article URL.
links_mobile_href	character	Mobile article URL.
links_api_self_href	character	ESPN API canonical self-link for the article resource.
links_app_sportscenter_href	character	SportsCenter app deep link.
links_web_self_href	character	Primary canonical web URL for this news article on ESPN.com.
links_web_self_dsi_href	character	Alternate canonical web URL for this news article using ESPN's DSI routing.
links_api_artwork_href	character	ESPN API URL for the artwork image associated with this news article.
links_sportscenter_href	character	Deep-link URL to this news article within the ESPN SportsCenter app or web experience.

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_cfb_news()

espn_cfb_injuries

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/injuries

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/injuries

API Parameter	Python	Pattern	Required	Nullable	Description

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
id	integer	ESPN numeric identifier for the athlete.
display_name	character	Athlete's full display name as shown on ESPN.
injuries	character	Injury entries for the athlete (list of dicts, stringified): status, type, details, dates.

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_cfb_injuries()

espn_cfb_transactions

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/transactions

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/transactions?limit=500

API Parameter	Python	Pattern	Required	Nullable	Description
limit	limit			Y	Maximum number of items to return.

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
date	character	Date of the poll release.
description	character	ESPN's description of the stat.
team_abbreviation	character	Team abbreviation.
team_alternate_color	character	Alternate team color.
team_color	character	Primary team color.
team_display_name	character	Full team display name.
team_id	integer	ESPN team id.
team_links	character
team_location	character	Team location / school name.
team_logos	character
team_name	character	Team nickname.

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_cfb_transactions()

espn_cfb_conferences

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/groups

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/groups

API Parameter	Python	Pattern	Required	Nullable	Description

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
group_id	integer	ESPN group (conference) id for the season.
name	character	Position name (e.g. Quarterback).
abbreviation	character	Metric abbreviation.
short_name	character	Ranking source short name (e.g. AP Poll).
is_conference	logical	TRUE for an actual conference, FALSE for a division roll-up.
parent_group_id	integer	group_id of the parent node (NA at the root).
depth	integer
children_count	integer

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_cfb_conferences()

espn_cfb_statistics_league

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/statistics

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/statistics

API Parameter	Python	Pattern	Required	Nullable	Description

Returns

return_parsed=True (default) — the output of parse_items; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: parser: parse_items returns no columns on the live payload (nba, nfl, mlb, nhl, wnba, cfb, mbb, wbb, 2026-10-07); its rows sit under keys it does not read (top level: league, season, status, timestamp).

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_cfb_statistics_league()

espn_cfb_draft

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/draft

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/draft

API Parameter	Python	Pattern	Required	Nullable	Description

Returns

return_parsed=True (default) — the output of parse_items; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: parser: parse_items returns no columns on the live payload (nba, nfl, nhl, wnba, 2026-10-07); its rows sit under keys it does not read (top level: breakingNews, broadcasts, displayName, picks, positions, rounds, shortDisplayName, status).

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_cfb_draft()

espn_cfb_player_info

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/{athlete_id}

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/4239

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

Returns

return_parsed=True (default) — the output of parse_single_entity; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: 404 in nba, nfl, mlb, nhl, wnba, cfb, mbb, wbb with the documented example arguments (2026-10-07).

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_cfb_player_info(athlete_id='4239')

espn_cfb_player_bio

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/{athlete_id}/bio

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/4239/bio

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

Returns

return_parsed=True (default) — the output of parse_single_entity; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: 404 in nba, nfl, mlb, nhl, wnba, cfb, mbb, wbb with the documented example arguments (2026-10-07).

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_cfb_player_bio(athlete_id='4239')

espn_cfb_player_news

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/{athlete_id}/news

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/athletes/4239/news

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
id	integer	ESPN numeric identifier for the article.
now_id	character	ESPN 'now' feed id.
content_key	character	Internal content key.
data_source_identifier	character	Source-system identifier.
type	character	Article type (Story, Media, HeadlineNews, etc.).
headline	character	Article headline.
description	character	Article summary/description.
last_modified	character	Last-modified timestamp (ISO 8601).
published	character	Publish timestamp (ISO 8601).
images	character	Article images (list, stringified).
categories	character	Article categories (list, stringified).
premium	logical	Whether the article is premium/paywalled.
byline	character	Author byline string as published by ESPN.
links_web_href	character	Web article URL.
links_mobile_href	character	Mobile article URL.
links_api_self_href	character	ESPN API canonical self-link for the article resource.
links_app_sportscenter_href	character	SportsCenter app deep link.
links_web_self_href	character	Primary canonical web URL for this news article on ESPN.com.
links_web_self_dsi_href	character	Alternate canonical web URL for this news article using ESPN's DSI routing.
links_api_artwork_href	character	ESPN API URL for the artwork image associated with this news article.
links_sportscenter_href	character	Deep-link URL to this news article within the ESPN SportsCenter app or web experience.

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_cfb_player_news(athlete_id='4239')

espn_cfb_standings

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/v2/sports/football/college-football/standings

Valid URL: https://site.api.espn.com/apis/v2/sports/football/college-football/standings

API Parameter	Python	Pattern	Required	Nullable	Description
season	season			Y	Season year (e.g. 2024).
group	group			Y	Conference or group id filter (e.g. an ESPN conference id).
type	standings_type			Y	Standings variant (e.g. 'by-division' or 'by-conference').

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
group_name	character	Group name.
group_abbreviation	character	Group abbreviation.
team_id	integer	Team id.
team_name	character	Team name.
team_abbreviation	character	Team abbreviation.
team_display_name	character	Team display name.
team_location	character	Team location.
team_logo	character	Team logo.
games_behind	double	Games behind.
league_win_percent	double	League win percent.
playoff_seed	double	Playoff seed.
point_differential	double	Point differential.
points_against	double	Points against.
points_for	double	Points for.
streak	double	Streak.
wins	double	Wins.
division_losses	double	Number of games the team has lost against opponents within their own division.
division_ties	double	Number of games the team has tied against opponents within their own division.
division_wins	double	Number of games the team has won against opponents within their own division.
overall	character	Overall.
home	character	Home.
away	character	Away team name.
vs. conf.	character	Vs. conf..
vs ap top 25	character	The team's win-loss record against opponents ranked in the AP Top 25 poll.
vs usa ranked teams	character	The team's win-loss record against opponents ranked in the USA Today Coaches Poll.
vs division	double	The team's win-loss(-tie) record against opponents within their own division, serialized as a numeric value.

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_cfb_standings()

espn_cfb_rankings

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/football/college-football/rankings

Valid URL: https://site.api.espn.com/apis/site/v2/sports/football/college-football/rankings

API Parameter	Python	Pattern	Required	Nullable	Description

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
poll_id	integer	ESPN poll id, e.g. 1 = AP Top 25, 2 = Coaches Poll, 20 = FCS Coaches Poll, 10624 = USCHO Men's Poll.
poll_name	character	Full poll name, e.g. 'AP Top 25', 'AFCA Coaches Poll', "USCHO Women's Poll".
poll_short_name	character	Short poll label, e.g. 'AP Poll'.
poll_type	character	ESPN poll type code, e.g. 'ap', 'usa' (coaches), 'fcs', 'USCHOMENSPOLL'.
season	integer	Season year of the poll (ESPN's ending year for a season that spans two calendar years, e.g. 2026 for 2025-26).
season_type	integer	Season phase of the poll: 1 = preseason, 2 = regular season, 3 = postseason.
week	integer	Poll week within season_type (the week ESPN's Core v2 rankings URL uses).
week_display	character	Poll week as ESPN labels it, e.g. 'Week 6'.
poll_date	character	Date the poll was released (ISO 8601, UTC).
ranked	logical	TRUE for the poll's ranked teams; FALSE for teams that only received votes.
team_id	integer	ESPN team id (Int64, like scoreboard home_id / away_id).
rank	integer	Position in the poll (1 = top). Null on vote-receiving rows.
previous_rank	integer	Position in the previous poll; 0 when the team was unranked then.
points	double	Poll points received (0 for polls ESPN ships without points, such as USCHO).
first_place_votes	integer	First-place votes received. Null when the poll does not report them.
trend	character	Movement since the previous poll as ESPN prints it, e.g. '+3', '-2', or '-' for no change.
record_summary	character	Team's win-loss record at the poll date, e.g. '5-0'.
team_uid	character	ESPN universal team id, e.g. 's:20l:23t:251'.
team_location	character	Team location (school name), e.g. 'Texas'.
team_name	character	Team mascot name, e.g. 'Longhorns'.
team_nickname	character	Short team name ESPN displays, e.g. 'Texas'.
team_abbreviation	character	Short team code ESPN displays, e.g. 'TEX'.
team_color	character	Team primary color as a hex string without '#'. Null for teams ESPN ships without one.
team_logo	character	URL of the team logo on ESPN's CDN.
last_updated	character	When ESPN last updated this poll entry (ISO 8601, UTC).

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_cfb_rankings()