Breaking in 4.0.0

• Public names are sportsdataverse-py's — athlete → player, event → game on every ESPN league; sdv-py's name_pattern on the native families (nhlApiWeb* → nhl*, nflApi* → nfl*, CBS's 16 shorts, the 3.0.0 file-stem names). Every pre-v4 name still works as a deprecated alias that warns once. (changelog)
• Integer id columns are decimal strings — Every id column of integers (id, *_id, game_pk, playerId, …) comes back as exact decimal strings on every surface — parsers, producers, loaders, HockeyTech analytics. Compare and join ids as strings; Number(row.game_id) for a safe number back. (changelog)
• 400 / 422 raise InvalidParameterError — For every family (it was AssetFetchError), never retried; the message names host, path and status with a redacted excerpt of the body. (changelog)
• Typed returns — generated row types for parsed: true — TypeScript only. A wrapper's raw payload resolves to unknown (was any); verified endpoints resolve to their row interfaces; the summary dispatchers to ParsedTables. Narrow or cast a raw payload. (changelog)
• Typed wrapper params and loader rows; strict mode — TypeScript only. A param the endpoint does not have, a missing required path param or a non-boolean bool param is a type error; parser rows are Record<string, unknown>; loader rows are their generated row types. (changelog)
• Wrapper failures raise NoDataError / AssetFetchError — Instead of raw axios errors. NoDataError = the fetch worked and there is nothing there (404, ESPN { code: 404 }); AssetFetchError = the fetch failed (403 / 429 / 5xx after retries, network). Retries follow DEFAULT_RETRY_STATUSES with backoff. (changelog)

cfb — CDN (espn.com page data)

5 endpoints on sdv.cfb. Each is exposed under a camelCase canonical name and a snake_case alias (py/R parity), accepts snake_case or camelCase params, and returns raw ESPN JSON by default ({ parsed: true } for tidy rows).

espnCfbCdnBoxscore

CFB — cdn boxscore (ESPN cdn.espn.com (espn.com page data)).

Endpoint URL: GET https://cdn.espn.com/core/college-football/boxscore?xhr=1

API param	JS	required	description
gameId	game_id	no	number | string — ESPN game (event) id
—	parsed	no	boolean — return tidy rows instead of raw JSON
—	section	no	with parsed, return one named sub-frame (e.g. boxscore, plays, winprobability) instead of all

Returns: raw ESPN Dict by default. With { parsed: true } the page's gamepackageJSON (a Site v2 summary) goes through the summary dispatcher, which returns an object of 21 sub-frames keyed by section ({ parsed: true, section: '<name>' } for one); see ESPN parsed returns.

Rows are untyped Row[] (not parity-verified yet).

Example:

await sdv.cfb.espnCfbCdnBoxscore({});
// snake_case alias (py/R parity): sdv.cfb.espn_cfb_cdn_boxscore(...)

espnCfbCdnPlaybyplay

CFB — cdn playbyplay (ESPN cdn.espn.com (espn.com page data)).

Endpoint URL: GET https://cdn.espn.com/core/college-football/playbyplay?xhr=1

API param	JS	required	description
gameId	game_id	no	number | string — ESPN game (event) id
—	parsed	no	boolean — return tidy rows instead of raw JSON
—	section	no	with parsed, return one named sub-frame (e.g. boxscore, plays, winprobability) instead of all

Returns: raw ESPN Dict by default. With { parsed: true } the page's gamepackageJSON (a Site v2 summary) goes through the summary dispatcher, which returns an object of 21 sub-frames keyed by section ({ parsed: true, section: '<name>' } for one); see ESPN parsed returns.

Rows are untyped Row[] (not parity-verified yet).

Example:

await sdv.cfb.espnCfbCdnPlaybyplay({});
// snake_case alias (py/R parity): sdv.cfb.espn_cfb_cdn_playbyplay(...)

espnCfbCdnRankings

CFB — cdn rankings (ESPN cdn.espn.com (espn.com page data)).

Endpoint URL: GET https://cdn.espn.com/core/college-football/rankings?xhr=1

API param	JS	required	description
week	week	no	number | string — Poll week. Defaults to the current week
year	season	no	number | string — Season year. Defaults to the current season
seasontype	season_type	no	number | string — Season phase: 1=preseason, 2=regular season, 3=postseason
—	parsed	no	boolean — return tidy rows instead of raw JSON

Returns (with { parsed: true }, via parse_cdn_rankings):

col_name	type	description
poll_id	integer	Poll id (1 = AP Top 25).
poll_name	character	Poll name (e.g. AP Top 25, AFCA Coaches Poll).
poll_short_name	character	Short poll name.
ranked	logical	true for a ranked team, false for a team receiving votes.
team_id	character	ESPN team id, read from team_url (null when the team is not linked).
team_display_name	character	Team display name.
trend	character	Movement since the previous poll.
formatted_record	character	Win-loss record (e.g. 4-0).
first_place_votes	integer	First-place votes.
rank	integer	Poll rank (null for teams receiving votes).
previous_rank	integer	Rank in the previous poll.
team_abbreviation	character	Team abbreviation.
team_url	character	espn.com team page URL.
team_logo	character	Team logo URL.
points	integer	Poll points.

Rows are untyped Row[] (not parity-verified yet).

Example:

await sdv.cfb.espnCfbCdnRankings({});
// snake_case alias (py/R parity): sdv.cfb.espn_cfb_cdn_rankings(...)

espnCfbCdnSchedule

CFB — cdn schedule (ESPN cdn.espn.com (espn.com page data)).

Endpoint URL: GET https://cdn.espn.com/core/college-football/schedule?xhr=1

API param	JS	required	description
date	date	no	number | string — Single date (YYYYMMDD). Ignored by cfb and nfl, which are week-oriented. Defaults to today
week	week	no	number | string — Week number (cfb and nfl)
year	season	no	number | string — Season year that week belongs to (cfb and nfl)
seasontype	season_type	no	number | string — Season phase for week: 1=preseason, 2=regular season, 3=postseason (cfb and nfl)
—	parsed	no	boolean — return tidy rows instead of raw JSON

Returns (with { parsed: true }, via parse_cdn_schedule):

col_name	type	description
game_id	character	ESPN game identifier.
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	character
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	integer	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	character	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	character	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	character
away_id	character	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	character

Rows are untyped Row[] (not parity-verified yet).

Example:

await sdv.cfb.espnCfbCdnSchedule({});
// snake_case alias (py/R parity): sdv.cfb.espn_cfb_cdn_schedule(...)

espnCfbCdnScoreboard

CFB — cdn scoreboard (ESPN cdn.espn.com (espn.com page data)).

Endpoint URL: GET https://cdn.espn.com/core/college-football/scoreboard?xhr=1

API param	JS	required	description
date	date	no	number | string — Single date (YYYYMMDD). Ignored by cfb and nfl, which are week-oriented. Defaults to today
week	week	no	number | string — Week number (cfb and nfl)
year	season	no	number | string — Season year that week belongs to (cfb and nfl)
seasontype	season_type	no	number | string — Season phase for week: 1=preseason, 2=regular season, 3=postseason (cfb and nfl)
—	parsed	no	boolean — return tidy rows instead of raw JSON

Returns (with { parsed: true }, via parse_cdn_scoreboard):

col_name	type	description
game_id	character	ESPN game identifier.
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	character
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	integer	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	character	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	character	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	character
away_id	character	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	character

Rows are untyped Row[] (not parity-verified yet).

Example:

await sdv.cfb.espnCfbCdnScoreboard({});
// snake_case alias (py/R parity): sdv.cfb.espn_cfb_cdn_scoreboard(...)

Generated by tools/codegen/generate.mjs from tools/codegen/endpoints/espn*.yaml (vendored from sdv-py) — see How this library is built._