Skip to main content

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

sportsdataverse.nfl — 4 endpoints.

espn_nfl_cdn_playbyplay​

One game's espn.com play-by-play page data. The gamepackageJSON block is a Site v2 summary (header, boxscore, plays or drives, win probability, ...), so the parsed result is the same dict of frames that parse_summary returns.

Endpoint URL: GET https://cdn.espn.com/core/nfl/playbyplay

Valid URL: https://cdn.espn.com/core/nfl/playbyplay?xhr=1&gameId=401671881

API ParameterPythonPatternRequiredNullableDescription
gameIdgame_idYESPN game (event) id.

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_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
team_locationStringTeam location.
athlete_idInt64Athlete id.
athlete_display_nameStringAthlete display name.
athlete_short_nameStringAthlete short name.
athlete_jerseyStringAthlete jersey.
athlete_positionStringAthlete position.
starterStringStarter.
activeStringActive.
did_not_playStringDid not play.
ejectedStringEjected.
reasonStringReason.
completions/passing_attemptsStringPass completion ratio for the player in the box score, expressed as completions divided by pass attempts.
passing_yardsStringNumeric yards by the passer_player_name, including yards gained in pass plays with laterals. This should equal official passing statistics.
yards_per_pass_attemptStringAverage passing yards gained per pass attempt by the player in the box score.
passing_touchdownsStringNumber of touchdown passes thrown by the player in the box score.
interceptionsStringThe number of interceptions thrown.
sacks_sack_yards_lostStringCombined sack statistics for the player, including sack count and total yards lost by the opposing offense.
adj_qbrStringESPN's Adjusted Quarterback Rating for the player, measuring overall passing efficiency on a 0-100 scale.
qb_ratingStringTraditional passer rating for the quarterback in the box score, calculated from completions, yards, touchdowns, and interceptions.
rushing_attemptsString
rushing_yardsStringNumeric yards by the rusher_player_name, excluding yards gained in rush plays with laterals. This should equal official rushing statistics but could miss yards gained in rush plays with laterals. Please see the description of lateral_rusher_player_name for further information.
yards_per_rush_attemptString
rushing_touchdownsStringNumber of rushing touchdowns scored by the player in the box score.
long_rushingStringLongest single rushing gain recorded by the player in the game.
receptionsStringThe number of pass receptions. Lateral receptions officially don't count as reception.
receiving_yardsStringNumeric yards by the receiver_player_name, excluding yards gained in pass plays with laterals. This should equal official receiving statistics but could miss yards gained in pass plays with laterals. Please see the description of lateral_receiver_player_name for further information.
yards_per_receptionStringAverage receiving yards gained per reception by the player in the box score.
receiving_touchdownsStringNumber of receiving touchdowns scored by the player in the box score.
long_receptionStringLongest single reception recorded by the player in the game.
receiving_targetsStringNumber of passing targets directed at the receiver during the game.
fumblesStringNumber of fumbles committed by the player in the box score.
fumbles_lostString
fumbles_recoveredString
total_tacklesStringTotal tackles recorded by the player, including both solo and assisted tackles.
solo_tacklesStringNumber of unassisted tackles recorded by the player in the box score.
sacksStringThe Number of times sacked.
tackles_for_lossString
passes_defendedStringNumber of pass plays disrupted or broken up by the defensive player in the game.
qb_hitsStringNumber of times the player made contact with the opposing quarterback after or during a pass attempt.
defensive_touchdownsStringNumber of touchdowns scored by the player via defensive plays such as interception or fumble returns.
interception_yardsString
interception_touchdownsStringNumber of touchdowns scored by the player on interception return plays.
kick_returnsString
kick_return_yardsString
yards_per_kick_returnStringAverage yards gained per kick return by the player in the box score.
long_kick_returnStringLongest single kick return yardage recorded by the player in the game.
kick_return_touchdownsStringNumber of touchdowns scored on kick returns by the player in the box score.
punt_returnsString
punt_return_yardsString
yards_per_punt_returnStringAverage yards gained per punt return by the player in the box score.
long_punt_returnStringLongest single punt return yardage recorded by the player in the game.
punt_return_touchdownsStringNumber of touchdowns scored on punt returns by the player in the box score.
puntsStringTotal number of punts executed by the player in the box score.
punt_yardsStringTotal yardage of all punts executed by the player in the game.
gross_avg_punt_yardsStringAverage gross punt distance before accounting for returns, recorded for the player in the game.
touchbacksStringNumber of punts or kick-offs by the player that resulted in the opposing team starting from their own end zone.
punts_inside20StringNumber of punts by the player that were downed or stopped inside the opposing team's 20-yard line.
long_puntStringDistance of the longest individual punt executed by the player in the game.
field_goals_made/field_goal_attemptsStringField goal conversion ratio for the player, expressed as field goals made divided by attempts.
field_goal_pctString
long_field_goal_madeStringDistance of the longest successful field goal kicked by the player in the game.
extra_points_made/extra_point_attemptsStringExtra point conversion ratio for the player, expressed as extra points made divided by attempts.
total_kicking_pointsStringTotal points contributed by the player through field goals and extra points in the game.

boxscore_team

col_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
home_awayStringHome away.
display_orderInt64Display order.
stat_nameStringStat name.
stat_labelStringStat label.
stat_display_valueStringStat display value.
stat_valueStringStat value.

winprobability

col_nametypedescription
home_win_percentageFloat64Home win percentage.
tie_percentageFloat64Tie percentage.
play_idInt64Play id.

leaders

col_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
category_nameStringCategory name.
category_display_nameStringCategory display name.
athlete_idInt64Athlete id.
athlete_display_nameStringAthlete display name.
athlete_positionStringAthlete position.
valueFloat64Value.
display_valueStringDisplay value.
main_statStringMain stat.
summaryStringSummary.

game_info

col_nametypedescription
attendanceInt64Attendance.
venue_idInt64Venue id.
venue_guidStringVenue guid.
venue_full_nameStringVenue full name.
venue_address_cityStringVenue address city.
venue_address_stateStringVenue address state.
venue_address_zip_codeStringPostal zip code of the venue where the game was played.
venue_address_countryStringCountry of the venue where the game was played.
venue_grassBooleanVenue grass.

officials

col_nametypedescription
full_nameStringFull name.
display_nameStringDisplay name.
orderInt64Order.
position_nameStringPosition name.
position_display_nameStringPosition display name.
position_idInt64Position id.

header

col_nametypedescription
idInt64Id.
uidStringUid.
time_validBooleanTime valid.
competitionsStringCompetitions.
linksStringLinks.
weekInt64Season week.
game_noteStringOptional editorial note or context annotation attached to the game in the header.
season_yearInt64Season year.
season_currentBooleanSeason current.
season_typeInt64Season type.
league_idInt64League id.
league_uidStringLeague uid.
league_nameStringLeague name.
league_abbreviationStringLeague abbreviation.
league_slugStringLeague slug.
league_is_tournamentBooleanLeague is tournament.
league_linksStringLeague links.
league_logosStringLeague logos.

standings

col_nametypedescription
group_headerStringGroup header.
conference_headerStringConference header.
division_headerStringDivision header.
team_idInt64Team id.
team_uidStringTeam uid.
team_locationStringTeam location.
lossesStringLosses.
points_againstString
points_forString
tiesString
win_percentStringWin percent.
winsStringWins.
overallString

format

col_nametypedescription
regulation_periodsInt64Regulation periods.
regulation_display_nameStringRegulation display name.
regulation_slugStringRegulation slug.
regulation_clockFloat64Regulation clock.
overtime_display_nameStringOvertime display name.
overtime_slugStringOvertime slug.
overtime_clockFloat64Overtime clock.
sudden_death_periodsInt64Number of sudden-death overtime periods defined in the game format rules.
sudden_death_clockFloat64Clock duration or time limit for sudden-death overtime periods as defined in the game format.

article

col_nametypedescription
idInt64Id.
now_idStringNow id.
content_keyStringContent key.
data_source_identifierStringData source identifier.
publishedkeyStringPublishedkey.
typeStringType.
game_idInt64Game id.
headlineStringHeadline.
descriptionStringDescription.
link_textStringLink text.
categorizedStringCategorized.
originally_postedStringOriginally posted.
last_modifiedStringLast modified.
publishedStringPublished.
sectionStringSection.
sourceStringSource.
imagesStringImages.
videoStringVideo.
categoriesStringCategories.
keywordsStringKeywords.
storyStringStory.
premiumBooleanPremium.
is_live_blogBooleanIs live blog.
allow_commentsBooleanAllow comments.
allow_searchBooleanAllow search.
allow_content_reactionsBooleanAllow content reactions.
links_web_hrefStringLinks web href.
links_mobile_hrefStringLinks mobile href.
links_api_self_hrefStringLinks api self href.
links_app_sportscenter_hrefStringLinks app sportscenter href.

injuries

col_nametypedescription
injuriesStringInjuries.
team_idInt64Team id.
team_uidStringTeam uid.
team_display_nameStringTeam display name.
team_abbreviationStringTeam abbreviation.
team_linksStringTeam links.
team_logoStringTeam logo.
team_logosStringTeam logos.

news

col_nametypedescription
idInt64Id.
now_idStringNow id.
content_keyStringContent key.
data_source_identifierStringData source identifier.
typeStringType.
headlineStringHeadline.
descriptionStringDescription.
last_modifiedStringLast modified.
publishedStringPublished.
imagesStringImages.
categoriesStringCategories.
premiumBooleanPremium.
bylineStringByline.
links_web_hrefStringLinks web href.
links_mobile_hrefStringLinks mobile href.
links_api_self_hrefStringLinks api self href.
links_app_sportscenter_hrefStringLinks app sportscenter href.

drives

col_nametypedescription
idInt64Id.
descriptionStringDescription.
yardsInt64The number of receiving yards
is_scoreBoolean
offensive_playsInt64
resultStringThe number of points the home team scored minus the number of points the visiting team scored. Equals h_score - v_score. Is NA for games which haven't yet been played. Convenient for evaluating against the spread bets.
short_display_resultString
display_resultString
playsString
team_idInt64Team id.
team_nameStringFull display name of the team.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
team_short_display_nameString
team_logosStringTeam logos.
start_period_typeString
start_period_numberInt64Period or quarter number in which the drive or sequence began.
start_clock_display_valueStringGame clock time displayed at the start of the drive or scoring sequence.
start_yard_lineInt64
start_textString
end_period_typeString
end_period_numberInt64Period or quarter number in which the drive or sequence ended.
end_clock_display_valueStringGame clock time displayed at the end of the drive or scoring sequence.
end_yard_lineInt64String indicating the yardline at the end of the given play consisting of team half and yard line number.
end_textString
time_elapsed_display_valueStringHuman-readable duration of time elapsed during the drive or scoring sequence.

drive_plays

col_nametypedescription
drive_idInt64
drive_sequenceInt64Sequential position of the drive within the game's broadcast or play-by-play listing.
idInt64Id.
sequence_numberStringSequence number.
textStringText.
away_scoreInt64Away score.
home_scoreInt64Home score.
scoring_playBooleanScoring play.
priorityBoolean
modifiedString
wallclockStringWallclock.
team_participantsStringTeams or participants associated with a specific drive or sequence in the broadcast record.
is_penaltyBoolean
stat_yardageInt64
is_turnoverBoolean
type_idInt64Type id.
type_textStringType text.
type_abbreviationString
period_numberInt64Period number.
clock_display_valueStringClock display value.
start_downInt64
start_distanceInt64
start_yard_lineInt64
start_yards_to_endzoneInt64
start_team_idInt64
end_downInt64
end_distanceInt64
end_yard_lineInt64String indicating the yardline at the end of the given play consisting of team half and yard line number.
end_yards_to_endzoneInt64
end_down_distance_textString
end_short_down_distance_textString
end_possession_textString
end_team_idInt64
start_down_distance_textString
start_short_down_distance_textString
start_possession_textString
scoring_type_nameString
scoring_type_display_nameString
scoring_type_abbreviationString
point_after_attempt_idInt64
point_after_attempt_textString
point_after_attempt_abbreviationString
point_after_attempt_valueFloat64

scoring_plays

col_nametypedescription
idInt64Id.
textStringText.
away_scoreInt64Away score.
home_scoreInt64Home score.
type_idInt64Type id.
type_textStringType text.
type_abbreviationString
period_numberInt64Period number.
clock_valueFloat64
clock_display_valueStringClock display value.
team_idInt64Team id.
team_uidStringTeam uid.
team_display_nameStringTeam display name.
team_abbreviationStringTeam abbreviation.
team_linksStringTeam links.
team_logoStringTeam logo.
team_logosStringTeam logos.
scoring_type_nameString
scoring_type_display_nameString
scoring_type_abbreviationString

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_nfl_cdn_playbyplay(game_id='401671881')

espn_nfl_cdn_boxscore​

One game's espn.com box-score page data, parsed like a Site v2 summary. For football the drives and scoring plays are only on the playbyplay page.

Endpoint URL: GET https://cdn.espn.com/core/nfl/boxscore

Valid URL: https://cdn.espn.com/core/nfl/boxscore?xhr=1&gameId=401671881

API ParameterPythonPatternRequiredNullableDescription
gameIdgame_idYESPN game (event) id.

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_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
team_locationStringTeam location.
athlete_idInt64Athlete id.
athlete_display_nameStringAthlete display name.
athlete_short_nameStringAthlete short name.
athlete_jerseyStringAthlete jersey.
athlete_positionStringAthlete position.
starterStringStarter.
activeStringActive.
did_not_playStringDid not play.
ejectedStringEjected.
reasonStringReason.
completions/passing_attemptsStringPass completion ratio for the player in the box score, expressed as completions divided by pass attempts.
passing_yardsStringNumeric yards by the passer_player_name, including yards gained in pass plays with laterals. This should equal official passing statistics.
yards_per_pass_attemptStringAverage passing yards gained per pass attempt by the player in the box score.
passing_touchdownsStringNumber of touchdown passes thrown by the player in the box score.
interceptionsStringThe number of interceptions thrown.
sacks_sack_yards_lostStringCombined sack statistics for the player, including sack count and total yards lost by the opposing offense.
adj_qbrStringESPN's Adjusted Quarterback Rating for the player, measuring overall passing efficiency on a 0-100 scale.
qb_ratingStringTraditional passer rating for the quarterback in the box score, calculated from completions, yards, touchdowns, and interceptions.
rushing_attemptsString
rushing_yardsStringNumeric yards by the rusher_player_name, excluding yards gained in rush plays with laterals. This should equal official rushing statistics but could miss yards gained in rush plays with laterals. Please see the description of lateral_rusher_player_name for further information.
yards_per_rush_attemptString
rushing_touchdownsStringNumber of rushing touchdowns scored by the player in the box score.
long_rushingStringLongest single rushing gain recorded by the player in the game.
receptionsStringThe number of pass receptions. Lateral receptions officially don't count as reception.
receiving_yardsStringNumeric yards by the receiver_player_name, excluding yards gained in pass plays with laterals. This should equal official receiving statistics but could miss yards gained in pass plays with laterals. Please see the description of lateral_receiver_player_name for further information.
yards_per_receptionStringAverage receiving yards gained per reception by the player in the box score.
receiving_touchdownsStringNumber of receiving touchdowns scored by the player in the box score.
long_receptionStringLongest single reception recorded by the player in the game.
receiving_targetsStringNumber of passing targets directed at the receiver during the game.
fumblesStringNumber of fumbles committed by the player in the box score.
fumbles_lostString
fumbles_recoveredString
total_tacklesStringTotal tackles recorded by the player, including both solo and assisted tackles.
solo_tacklesStringNumber of unassisted tackles recorded by the player in the box score.
sacksStringThe Number of times sacked.
tackles_for_lossString
passes_defendedStringNumber of pass plays disrupted or broken up by the defensive player in the game.
qb_hitsStringNumber of times the player made contact with the opposing quarterback after or during a pass attempt.
defensive_touchdownsStringNumber of touchdowns scored by the player via defensive plays such as interception or fumble returns.
interception_yardsString
interception_touchdownsStringNumber of touchdowns scored by the player on interception return plays.
kick_returnsString
kick_return_yardsString
yards_per_kick_returnStringAverage yards gained per kick return by the player in the box score.
long_kick_returnStringLongest single kick return yardage recorded by the player in the game.
kick_return_touchdownsStringNumber of touchdowns scored on kick returns by the player in the box score.
punt_returnsString
punt_return_yardsString
yards_per_punt_returnStringAverage yards gained per punt return by the player in the box score.
long_punt_returnStringLongest single punt return yardage recorded by the player in the game.
punt_return_touchdownsStringNumber of touchdowns scored on punt returns by the player in the box score.
puntsStringTotal number of punts executed by the player in the box score.
punt_yardsStringTotal yardage of all punts executed by the player in the game.
gross_avg_punt_yardsStringAverage gross punt distance before accounting for returns, recorded for the player in the game.
touchbacksStringNumber of punts or kick-offs by the player that resulted in the opposing team starting from their own end zone.
punts_inside20StringNumber of punts by the player that were downed or stopped inside the opposing team's 20-yard line.
long_puntStringDistance of the longest individual punt executed by the player in the game.
field_goals_made/field_goal_attemptsStringField goal conversion ratio for the player, expressed as field goals made divided by attempts.
field_goal_pctString
long_field_goal_madeStringDistance of the longest successful field goal kicked by the player in the game.
extra_points_made/extra_point_attemptsStringExtra point conversion ratio for the player, expressed as extra points made divided by attempts.
total_kicking_pointsStringTotal points contributed by the player through field goals and extra points in the game.

boxscore_team

col_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
home_awayStringHome away.
display_orderInt64Display order.
stat_nameStringStat name.
stat_labelStringStat label.
stat_display_valueStringStat display value.
stat_valueStringStat value.

winprobability

col_nametypedescription
home_win_percentageFloat64Home win percentage.
tie_percentageFloat64Tie percentage.
play_idInt64Play id.

leaders

col_nametypedescription
team_idInt64Team id.
team_abbreviationStringTeam abbreviation.
category_nameStringCategory name.
category_display_nameStringCategory display name.
athlete_idInt64Athlete id.
athlete_display_nameStringAthlete display name.
athlete_positionStringAthlete position.
valueFloat64Value.
display_valueStringDisplay value.
main_statStringMain stat.
summaryStringSummary.

game_info

col_nametypedescription
attendanceInt64Attendance.
venue_idInt64Venue id.
venue_guidStringVenue guid.
venue_full_nameStringVenue full name.
venue_address_cityStringVenue address city.
venue_address_stateStringVenue address state.
venue_address_zip_codeStringPostal zip code of the venue where the game was played.
venue_address_countryStringCountry of the venue where the game was played.
venue_grassBooleanVenue grass.

officials

col_nametypedescription
full_nameStringFull name.
display_nameStringDisplay name.
orderInt64Order.
position_nameStringPosition name.
position_display_nameStringPosition display name.
position_idInt64Position id.

header

col_nametypedescription
idInt64Id.
uidStringUid.
time_validBooleanTime valid.
competitionsStringCompetitions.
linksStringLinks.
weekInt64Season week.
game_noteStringOptional editorial note or context annotation attached to the game in the header.
season_yearInt64Season year.
season_currentBooleanSeason current.
season_typeInt64Season type.
league_idInt64League id.
league_uidStringLeague uid.
league_nameStringLeague name.
league_abbreviationStringLeague abbreviation.
league_slugStringLeague slug.
league_is_tournamentBooleanLeague is tournament.
league_linksStringLeague links.
league_logosStringLeague logos.

standings

col_nametypedescription
group_headerStringGroup header.
conference_headerStringConference header.
division_headerStringDivision header.
team_idInt64Team id.
team_uidStringTeam uid.
team_locationStringTeam location.
lossesStringLosses.
points_againstString
points_forString
tiesString
win_percentStringWin percent.
winsStringWins.
overallString

format

col_nametypedescription
regulation_periodsInt64Regulation periods.
regulation_display_nameStringRegulation display name.
regulation_slugStringRegulation slug.
regulation_clockFloat64Regulation clock.
overtime_display_nameStringOvertime display name.
overtime_slugStringOvertime slug.
overtime_clockFloat64Overtime clock.
sudden_death_periodsInt64Number of sudden-death overtime periods defined in the game format rules.
sudden_death_clockFloat64Clock duration or time limit for sudden-death overtime periods as defined in the game format.

article

col_nametypedescription
idInt64Id.
now_idStringNow id.
content_keyStringContent key.
data_source_identifierStringData source identifier.
publishedkeyStringPublishedkey.
typeStringType.
game_idInt64Game id.
headlineStringHeadline.
descriptionStringDescription.
link_textStringLink text.
categorizedStringCategorized.
originally_postedStringOriginally posted.
last_modifiedStringLast modified.
publishedStringPublished.
sectionStringSection.
sourceStringSource.
imagesStringImages.
videoStringVideo.
categoriesStringCategories.
keywordsStringKeywords.
storyStringStory.
premiumBooleanPremium.
is_live_blogBooleanIs live blog.
allow_commentsBooleanAllow comments.
allow_searchBooleanAllow search.
allow_content_reactionsBooleanAllow content reactions.
links_web_hrefStringLinks web href.
links_mobile_hrefStringLinks mobile href.
links_api_self_hrefStringLinks api self href.
links_app_sportscenter_hrefStringLinks app sportscenter href.

injuries

col_nametypedescription
injuriesStringInjuries.
team_idInt64Team id.
team_uidStringTeam uid.
team_display_nameStringTeam display name.
team_abbreviationStringTeam abbreviation.
team_linksStringTeam links.
team_logoStringTeam logo.
team_logosStringTeam logos.

news

col_nametypedescription
idInt64Id.
now_idStringNow id.
content_keyStringContent key.
data_source_identifierStringData source identifier.
typeStringType.
headlineStringHeadline.
descriptionStringDescription.
last_modifiedStringLast modified.
publishedStringPublished.
imagesStringImages.
categoriesStringCategories.
premiumBooleanPremium.
bylineStringByline.
links_web_hrefStringLinks web href.
links_mobile_hrefStringLinks mobile href.
links_api_self_hrefStringLinks api self href.
links_app_sportscenter_hrefStringLinks app sportscenter href.

drives

col_nametypedescription
idInt64Id.
descriptionStringDescription.
yardsInt64The number of receiving yards
is_scoreBoolean
offensive_playsInt64
resultStringThe number of points the home team scored minus the number of points the visiting team scored. Equals h_score - v_score. Is NA for games which haven't yet been played. Convenient for evaluating against the spread bets.
short_display_resultString
display_resultString
playsString
team_idInt64Team id.
team_nameStringFull display name of the team.
team_abbreviationStringTeam abbreviation.
team_display_nameStringTeam display name.
team_short_display_nameString
team_logosStringTeam logos.
start_period_typeString
start_period_numberInt64Period or quarter number in which the drive or sequence began.
start_clock_display_valueStringGame clock time displayed at the start of the drive or scoring sequence.
start_yard_lineInt64
start_textString
end_period_typeString
end_period_numberInt64Period or quarter number in which the drive or sequence ended.
end_clock_display_valueStringGame clock time displayed at the end of the drive or scoring sequence.
end_yard_lineInt64String indicating the yardline at the end of the given play consisting of team half and yard line number.
end_textString
time_elapsed_display_valueStringHuman-readable duration of time elapsed during the drive or scoring sequence.

drive_plays

col_nametypedescription
drive_idInt64
drive_sequenceInt64Sequential position of the drive within the game's broadcast or play-by-play listing.
idInt64Id.
sequence_numberStringSequence number.
textStringText.
away_scoreInt64Away score.
home_scoreInt64Home score.
scoring_playBooleanScoring play.
priorityBoolean
modifiedString
wallclockStringWallclock.
team_participantsStringTeams or participants associated with a specific drive or sequence in the broadcast record.
is_penaltyBoolean
stat_yardageInt64
is_turnoverBoolean
type_idInt64Type id.
type_textStringType text.
type_abbreviationString
period_numberInt64Period number.
clock_display_valueStringClock display value.
start_downInt64
start_distanceInt64
start_yard_lineInt64
start_yards_to_endzoneInt64
start_team_idInt64
end_downInt64
end_distanceInt64
end_yard_lineInt64String indicating the yardline at the end of the given play consisting of team half and yard line number.
end_yards_to_endzoneInt64
end_down_distance_textString
end_short_down_distance_textString
end_possession_textString
end_team_idInt64
start_down_distance_textString
start_short_down_distance_textString
start_possession_textString
scoring_type_nameString
scoring_type_display_nameString
scoring_type_abbreviationString
point_after_attempt_idInt64
point_after_attempt_textString
point_after_attempt_abbreviationString
point_after_attempt_valueFloat64

scoring_plays

col_nametypedescription
idInt64Id.
textStringText.
away_scoreInt64Away score.
home_scoreInt64Home score.
type_idInt64Type id.
type_textStringType text.
type_abbreviationString
period_numberInt64Period number.
clock_valueFloat64
clock_display_valueStringClock display value.
team_idInt64Team id.
team_uidStringTeam uid.
team_display_nameStringTeam display name.
team_abbreviationStringTeam abbreviation.
team_linksStringTeam links.
team_logoStringTeam logo.
team_logosStringTeam logos.
scoring_type_nameString
scoring_type_display_nameString
scoring_type_abbreviationString

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_nfl_cdn_boxscore(game_id='401671881')

espn_nfl_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/nfl/schedule

Valid URL: https://cdn.espn.com/core/nfl/schedule?xhr=1&week=5&year=2024&seasontype=2

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.
uidString
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_idInt64
status_type_nameString
status_type_stateString
status_type_completedBoolean
status_type_descriptionString
status_type_detailString
status_type_short_detailString
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_clockString
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_competitionBoolean
attendanceInt64
venue_idInt64
venue_full_nameString
venue_cityString
venue_stateString
venue_indoorBoolean
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_idInt64
home_nameString
home_abbreviationString
home_display_nameString
home_locationString
home_colorString
home_alternate_colorString
home_logoString
home_scoreStringHome team's score. For cricket, the innings string (e.g. '161/5 (18/20 ov, target 156)').
home_winnerBoolean
home_rankString
away_idInt64
away_nameString
away_abbreviationString
away_display_nameString
away_locationString
away_colorString
away_alternate_colorString
away_logoString
away_scoreStringAway team's score. For cricket, the innings string.
away_winnerBoolean
away_rankString

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_nfl_cdn_schedule(season=2024, week=5, season_type=2)

espn_nfl_cdn_scoreboard​

espn.com scoreboard page data for one day (one week for football), one row per game. The page's sbData block is a Site v2 scoreboard payload.

Endpoint URL: GET https://cdn.espn.com/core/nfl/scoreboard

Valid URL: https://cdn.espn.com/core/nfl/scoreboard?xhr=1&week=5&year=2024&seasontype=2

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.
uidString
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_idInt64
status_type_nameString
status_type_stateString
status_type_completedBoolean
status_type_descriptionString
status_type_detailString
status_type_short_detailString
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_clockString
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_competitionBoolean
attendanceInt64
venue_idInt64
venue_full_nameString
venue_cityString
venue_stateString
venue_indoorBoolean
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_idInt64
home_nameString
home_abbreviationString
home_display_nameString
home_locationString
home_colorString
home_alternate_colorString
home_logoString
home_scoreStringHome team's score. For cricket, the innings string (e.g. '161/5 (18/20 ov, target 156)').
home_winnerBoolean
home_rankString
away_idInt64
away_nameString
away_abbreviationString
away_display_nameString
away_locationString
away_colorString
away_alternate_colorString
away_logoString
away_scoreStringAway team's score. For cricket, the innings string.
away_winnerBoolean
away_rankString

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_nfl_cdn_scoreboard(season=2024, week=5, season_type=2)