Skip to main content

NHL — ESPN CDN API (cdn.espn.com)

sportsdataverse.nhl — 1 endpoint.

espn_nhl_cdn_schedule​

espn.com schedule page data, one row per game: up to 7 days starting at date (mbb and wbb: that day only; cfb and nfl: one week).

Endpoint URL: GET https://cdn.espn.com/core/nhl/schedule

Valid URL: https://cdn.espn.com/core/nhl/schedule?xhr=1&date=20250115

API ParameterPythonPatternRequiredNullableDescription
datedateYSingle date (YYYYMMDD). Ignored by cfb and nfl, which are week-oriented. Defaults to today.
weekweekYWeek number (cfb and nfl).
yearseasonYSeason year that week belongs to (cfb and nfl).
seasontypeseason_typeYSeason phase for week: 1=preseason, 2=regular season, 3=postseason (cfb and nfl).

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
game_idInt64ESPN event id.
uidStringCompetitor uid string.
dateStringMatch start timestamp (ISO 8601, UTC).
nameStringFull event name (e.g. 'Team A at Team B').
short_nameStringAbbreviated event name (e.g. 'TA @ TB').
season_yearInt64Integer season year ESPN assigns the event (e.g. 2025 for the 2025-26 season).
season_typeInt64ESPN 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_slugStringESPN 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_idInt64Status type identifier.
status_type_nameStringStatus type name.
status_type_stateStringStatus state (pre/in/post).
status_type_completedBooleanWhether the game is complete.
status_type_descriptionStringStatus description.
status_type_detailStringStatus detail text.
status_type_short_detailStringShort status detail.
status_clockFloat64Game 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_clockStringDisplay clock string.
status_periodInt64Current or final period number (quarter, half, inning or period, depending on the sport).
neutral_siteBooleanWhether the match is played at a neutral venue.
conference_competitionBooleanWhether it is a conference competition.
attendanceInt64Game attendance.
venue_idInt64Venue identifier.
venue_full_nameStringVenue full name.
venue_cityStringVenue city.
venue_stateStringVenue state.
venue_indoorBooleanWhether the venue is indoors.
broadcastStringEvery 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.
noteStringEvent 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_idInt64Home team ESPN identifier.
home_nameStringHome team display name.
home_abbreviationStringHome team abbreviation.
home_display_nameStringHome team display name.
home_locationStringHome team city.
home_colorStringHome team primary color hex.
home_alternate_colorStringHome team alternate color hex.
home_logoStringHome team logo URL.
home_scoreStringHome team's score. For cricket, the innings string (e.g. '161/5 (18/20 ov, target 156)').
home_winnerBooleanWhether the home team won.
home_rankStringHome team rank (if ranked).
away_idInt64Away team ESPN identifier.
away_nameStringAway team display name.
away_abbreviationStringAway team abbreviation.
away_display_nameStringAway team display name.
away_locationStringAway team city.
away_colorStringAway team primary color hex.
away_alternate_colorStringAway team alternate color hex.
away_logoStringAway team logo URL.
away_scoreStringAway team's score. For cricket, the innings string.
away_winnerBooleanWhether the away team won.
away_rankStringAway team rank (if ranked).

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_nhl_cdn_schedule(date='20250115')