Skip to main content

UEFA Champions League — ESPN site API (v2)

sportsdataverse.soccer.ucl — 24 endpoints.

espn_ucl_scoreboard​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/scoreboard

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/scoreboard?dates=20240115&limit=500

API ParameterPythonPatternRequiredNullableDescription
datesdatesYOne day (YYYYMMDD) or one calendar year (YYYY). A range (YYYYMMDD-YYYYMMDD) is rejected with HTTP 400; request each day, or use the Core v2 events wrapper.
weekweekYWeek number within the season.
seasontypeseason_typeYSeason phase: 1=preseason, 2=regular season, 3=postseason.
groupsgroupsYConference or group id filter (e.g. an ESPN conference id).
limitlimitYMaximum 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_nametypedescription
event_idStringESPN event id for the match.
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_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').
tournamentStringShort tournament the match belongs to, derived from the season-type slug: 'apertura' (July-December) or 'clausura' (January-May) for split-season leagues such as Liga MX, null for single-tournament leagues.
home_teamStringHome team display name.
home_team_idStringHome team ESPN id.
home_scoreStringHome team's score. For cricket, the innings string (e.g. '161/5 (18/20 ov, target 156)').
away_teamStringAway team display name.
away_team_idStringAway team ESPN id.
away_scoreStringAway team's score. For cricket, the innings string.
statusStringStatus type name (e.g. STATUS_FINAL, STATUS_SCHEDULED, STATUS_IN_PROGRESS).
venueStringFull name of the venue where the match was played.

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

espn_ucl_summary​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/summary

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/summary

API ParameterPythonPatternRequiredNullableDescription
eventevent_idYevent 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).

header

col_nametypedescription
idString
uidString
time_validBoolean
season_yearInt64
season_typeInt64ESPN season-phase numeric code (1=pre-season, 2=regular season, 3=postseason, 4=off-season).
season_slugString
tournamentStringShort tournament the match belongs to, derived from the header season-type name: 'apertura' (July-December) or 'clausura' (January-May) for split-season leagues such as Liga MX, null for single-tournament leagues; soccer summaries only.
league_idStringESPN numeric identifier for the league or competition.
league_nameString
league_abbreviationStringAbbreviation for the league or competition the game belongs to.
competition_idStringESPN numeric identifier for the primary competition (game) in the header.
competition_dateStringDate and time of the competition as recorded in the game header.
neutral_siteBoolean
status_nameString
status_descriptionString
is_finalBooleanBoolean flag indicating whether the game has reached a final or completed status.

lineups

col_nametypedescription
team_idString
home_awayString
athleteStringReference or identifier string for the athlete associated with this row in the box score.
athlete_idString
positionString
starterBoolean
jerseyString
formation_placeStringStarting formation position or role assigned to the player within the team lineup for the match.
subbed_inBooleanIndicates whether the player entered the game as a substitute, or the minute of substitution.
subbed_outBooleanIndicates whether the player was substituted out of the game, or the minute of substitution.

key_events

col_nametypedescription
idString
typeString
type_idString
type_slugString
textString
short_textString
clockString
clock_valueFloat64
periodInt64
team_idString
team_nameStringFull display name of the team.
scoring_playBoolean
field_position_xFloat64Distance of the event from the goal line the event's team attacks, as a fraction of half the pitch (penalty spot = 0.23); 0 together with a 0 y means ESPN recorded no location.
field_position_yFloat64Position of the event across the pitch from 0 to 1, where values below 0.5 are the attacking team's left; 0 together with a 0 x means ESPN recorded no location.
field_position2_xFloat64Distance of the event's end location from the goal line the team attacks, as a fraction of half the pitch, in the same frame as field_position_x; 0 when not recorded.
field_position2_yFloat64Position of the event's end location across the pitch from 0 to 1, in the same frame as field_position_y; 0 when not recorded.
goal_position_xFloat64Horizontal position at which a shot crossed the goal frame; 0 when not recorded.
goal_position_yFloat64Vertical position at which a shot crossed the goal frame; 0 when not recorded.
source_idString
source_descriptionString
athlete_idString
athlete_nameString
wallclockString

team_stats

col_nametypedescription
team_idString
team_nameStringFull display name of the team.
team_abbreviationString
home_awayString
fouls_committedStringTotal number of fouls committed by the team during the match.
yellow_cardsStringTotal number of yellow cards received by the team during the match.
red_cardsStringTotal number of red cards received by the team during the match.
offsidesStringTotal number of offside calls against the team during the match.
won_cornersStringTotal number of corner kicks earned by the team during the match.
savesString
possession_pctStringPercentage of total ball possession time held by the team during the match.
total_shotsStringTotal number of shot attempts taken by the team during the match.
shots_on_targetStringNumber of the team's shot attempts that were on target, requiring a save or resulting in a goal.
shot_pctStringPercentage of the team's shot attempts that were on target during the match.
penalty_kick_goalsStringNumber of goals scored by the team from penalty kicks during the match.
penalty_kick_shotsStringNumber of penalty kick attempts taken by the team during the match.
accurate_passesStringNumber of passes completed successfully by the team during the match.
total_passesStringTotal number of passes attempted by the team during the match.
pass_pctStringPercentage of passes attempted by the team that were completed successfully.
accurate_crossesStringNumber of crosses into the opponent's area completed successfully by the team.
total_crossesStringTotal number of crossing attempts made by the team during the match.
cross_pctStringPercentage of the team's crossing attempts that were accurate during the match.
total_long_ballsStringTotal number of long-ball passes attempted by the team during the match.
accurate_long_ballsStringNumber of long-ball passes completed successfully by the team during the match.
longball_pctStringPercentage of long-ball attempts by the team that were accurate during the match.
blocked_shotsString
effective_tacklesStringNumber of tackles by the team that successfully dispossessed the opposing player.
total_tacklesStringTotal tackles recorded by the player, including both solo and assisted tackles.
tackle_pctStringPercentage of the team's tackle attempts that were effective in winning possession.
interceptionsString
effective_clearanceStringNumber of defensive clearances that successfully removed the ball from the danger area for the team.
total_clearanceStringTotal number of defensive clearances made by the team during the match.

commentary

col_nametypedescription
sequenceInt64
time_displayStringHuman-readable game clock time at which a match event occurred.
time_valueFloat64Numeric game clock value at which a match event occurred.
textString
play_idString
play_typeString
play_type_idString
play_type_slugStringESPN's lowercase slug for the play type of the linked play, e.g. foul or goal.
play_textString
play_short_textStringESPN's short label for the play linked to this commentary item, e.g. a player name followed by the event type.
periodInt64
clockString
clock_valueFloat64
scoring_playBoolean
team_nameStringFull display name of the team.
athlete_idString
athlete_nameString
field_position_xFloat64Distance of the event from the goal line the event's team attacks, as a fraction of half the pitch (penalty spot = 0.23); 0 together with a 0 y means ESPN recorded no location.
field_position_yFloat64Position of the event across the pitch from 0 to 1, where values below 0.5 are the attacking team's left; 0 together with a 0 x means ESPN recorded no location.
field_position2_xFloat64Distance of the event's end location from the goal line the team attacks, as a fraction of half the pitch, in the same frame as field_position_x; 0 when not recorded.
field_position2_yFloat64Position of the event's end location across the pitch from 0 to 1, in the same frame as field_position_y; 0 when not recorded.
goal_position_xFloat64Horizontal position at which a shot crossed the goal frame; 0 when not recorded.
goal_position_yFloat64Vertical position at which a shot crossed the goal frame; 0 when not recorded.
wallclockString

leaders

col_nametypedescription
team_idString
team_nameStringFull display name of the team.
categoryString
category_slugStringMachine-readable slug identifying the statistical category the player entry belongs to in the box score.
athlete_idString
athleteStringReference or identifier string for the athlete associated with this row in the box score.
athlete_positionString
valueString
main_stat_labelStringHuman-readable label for the primary statistic displayed for the player in the box score.
main_stat_valueStringValue of the primary statistic displayed for the player in the box score.
summaryString

standings

col_nametypedescription
groupString
teamString
team_idString
team_uidString
games_playedFloat64
lossesFloat64
point_differentialFloat64
pointsFloat64
tiesFloat64
winsFloat64
rankFloat64
overallString

head_to_head

col_nametypedescription
event_idString
game_dateString
at_vsString
scoreString
home_team_idString
away_team_idString
home_team_scoreString
away_team_scoreString
home_aggregate_scoreStringAggregate score for the home team across both legs of the two-legged tie.
away_aggregate_scoreStringAggregate score for the away team across both legs of the two-legged tie.
home_shootout_scoreStringNumber of penalties scored by the home team in a shootout to decide the tie.
away_shootout_scoreStringNumber of penalties scored by the away team in a shootout to decide the tie.
game_resultString
match_noteStringOptional editorial note or special circumstance annotation attached to this match in the series.
competition_nameStringFull name of the competition or tournament to which this series match belongs.
round_nameStringName or label for the round or stage of the competition in which this series match is played.
league_nameString
league_abbreviationStringAbbreviation for the league or competition the game belongs to.
opponentInt64
perspective_team_idStringESPN identifier for the team whose perspective is used to orient the series or match result display.

last_five

col_nametypedescription
team_idString
team_nameStringFull display name of the team.
display_orderInt64Numeric order in which the team or entry is displayed within the box score table.
event_idString
game_dateString
at_vsString
scoreString
home_team_idString
away_team_idString
home_team_scoreString
away_team_scoreString
game_resultString
competition_nameStringFull name of the competition or tournament to which this series match belongs.
league_nameString
league_abbreviationStringAbbreviation for the league or competition the game belongs to.
opponentInt64

game_info

col_nametypedescription
venue_idString
venue_full_nameString
venue_short_nameStringAbbreviated or shortened display name for the venue where the game was played.
venue_cityString
venue_countryStringCountry name for the venue where the game was played.
attendanceInt64
officialsString

shootout

col_nametypedescription
team_entry_idStringESPN identifier for the team entry associated with this shootout or penalty record.
team_nameStringFull display name of the team.
shot_idStringESPN identifier for an individual shootout or penalty kick attempt.
player_idString
playerString
shot_numberInt64Sequential number of the penalty kick or shootout attempt within the series.
did_scoreBooleanBoolean flag indicating whether the penalty kick or shootout attempt resulted in a goal.

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

espn_ucl_calendar​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/calendar

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/calendar

API ParameterPythonPatternRequiredNullableDescription

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​

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

espn_ucl_news​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/news

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/news?limit=50

API ParameterPythonPatternRequiredNullableDescription
limitlimitYMaximum 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_nametypedescription
idInt64ESPN numeric identifier for the article.
now_idStringESPN 'now' feed id.
content_keyStringInternal content key.
data_source_identifierStringSource-system identifier.
typeStringArticle type (Story, Media, HeadlineNews, etc.).
headlineStringArticle headline.
descriptionStringArticle summary/description.
last_modifiedStringLast-modified timestamp (ISO 8601).
publishedStringPublish timestamp (ISO 8601).
imagesStringArticle images (list, stringified).
categoriesStringArticle categories (list, stringified).
premiumBooleanWhether the article is premium/paywalled.
bylineStringAuthor byline string as published by ESPN.
links_web_hrefStringWeb article URL.
links_mobile_hrefStringMobile article URL.
links_api_self_hrefStringESPN API canonical self-link for the article resource.
links_app_sportscenter_hrefStringSportsCenter app deep link.

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

espn_ucl_injuries​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/injuries

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/injuries

API ParameterPythonPatternRequiredNullableDescription

Returns​

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

col_nametypedescription
idInt64ESPN numeric identifier for the athlete.
display_nameStringAthlete's full display name as shown on ESPN.
injuriesStringInjury entries for the athlete (list of dicts, stringified): status, type, details, dates.

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

espn_ucl_transactions​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/transactions

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/transactions?limit=500

API ParameterPythonPatternRequiredNullableDescription
limitlimitYMaximum 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_nametypedescription
dateString
descriptionString
team_abbreviationString
team_alternate_colorString
team_colorString
team_display_nameString
team_idInt64
team_linksString
team_locationString
team_logosString
team_nameString

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

espn_ucl_conferences​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/groups

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/groups

API ParameterPythonPatternRequiredNullableDescription

Returns​

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

col_nametypedescription
group_idInt64
nameString
abbreviationString
short_nameString
is_conferenceBoolean
parent_group_idInt64
depthInt64
children_countInt64

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

espn_ucl_statistics_league​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/statistics

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/statistics

API ParameterPythonPatternRequiredNullableDescription

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​

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

espn_ucl_draft​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/draft

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/draft

API ParameterPythonPatternRequiredNullableDescription

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​

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

espn_ucl_teams_site​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams?limit=1000

API ParameterPythonPatternRequiredNullableDescription
limitlimitYMaximum 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_nametypedescription
team_idStringESPN numeric identifier for the team.
display_nameStringFull display name of the team (e.g. 'Los Angeles Lakers').
abbreviationStringTeam abbreviation.
locationStringTeam location/city.
nameStringShort team name, typically the mascot (e.g. 'Lakers').
short_display_nameStringShort team display name.
nicknameStringAlternative nickname used by ESPN for the team.
slugStringURL slug for the team.
uidStringESPN universal id for the team.
colorStringPrimary team color (hex).
alternate_colorStringSecondary team color (hex).
is_activeBooleanWhether the team is currently active.
is_all_starBooleanWhether the team is an all-star side.

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

espn_ucl_team​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_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_nametypedescription
team_abbreviationString
team_alternate_colorString
team_colorString
team_display_nameString
team_franchise_$refString
team_franchise_abbreviationString
team_franchise_colorString
team_franchise_display_nameString
team_franchise_idInt64
team_franchise_is_activeBoolean
team_franchise_locationString
team_franchise_nameString
team_franchise_short_display_nameString
team_franchise_slugString
team_franchise_team_$refString
team_franchise_uidString
team_franchise_venue_$refString
team_franchise_venue_address_cityString
team_franchise_venue_address_stateString
team_franchise_venue_full_nameString
team_franchise_venue_grassBoolean
team_franchise_venue_guidString
team_franchise_venue_idInt64
team_franchise_venue_imagesString
team_franchise_venue_indoorBoolean
team_franchise_venue_short_nameString
team_groups_idInt64
team_groups_is_conferenceBoolean
team_groups_parent_idInt64
team_idInt64
team_is_activeBoolean
team_linksString
team_locationString
team_logosString
team_nameString
team_next_eventString
team_record_itemsString
team_short_display_nameString
team_slugString
team_standing_summaryString
team_uidString

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_ucl_team(team_id='4')

espn_ucl_team_roster​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/roster

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/roster?limit=500

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
limitlimitYMaximum 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_nametypedescription
athlete_idStringESPN numeric identifier for the athlete.
uidStringESPN universal id for the athlete.
first_nameStringAthlete's first (given) name.
last_nameStringAthlete's last (family) name.
display_nameStringAthlete's full display name as shown on ESPN.
short_nameStringAthlete's abbreviated display name (e.g. 'L. James').
jerseyStringAthlete's jersey number as a string.
ageInt64Athlete age in years.
date_of_birthStringAthlete date of birth (ISO 8601).
heightFloat64Athlete height in inches.
display_heightStringAthlete height, formatted for display.
weightFloat64Athlete weight in pounds.
display_weightStringAthlete weight, formatted for display.
positionStringPosition abbreviation.
position_nameStringFull position name (e.g. 'Point Guard', 'Goalkeeper').
birth_cityStringAthlete birth city.
birth_countryStringAthlete birth country.
citizenshipStringAthlete citizenship.
genderStringAthlete gender.
slugStringURL slug for the athlete.
statusStringRoster status (e.g. Active).

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_ucl_team_roster(team_id='4')

espn_ucl_team_schedule​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/schedule

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/schedule

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
seasonseasonYSeason year (e.g. 2024).

Returns​

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

col_nametypedescription
idInt64ESPN numeric event identifier.
dateStringEvent timestamp (ISO 8601, UTC).
nameStringFull event name (e.g. 'Team A at Team B').
short_nameStringAbbreviated event name (e.g. 'TA @ TB').
time_validBooleanWhether the event time is confirmed.
competitionsStringCompetition detail (list of dicts, stringified): competitors, venue, status.
linksStringRelated links (list, stringified).
season_yearInt64Four-digit season year.
season_display_nameStringHuman-readable season label (e.g. '2024-25').
season_type_idInt64ESPN numeric identifier for the season type.
season_type_typeInt64Season type numeric code.
season_type_nameStringSeason type name (e.g. Regular Season).
season_type_abbreviationStringSeason type abbreviation.

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_ucl_team_schedule(team_id='4')

espn_ucl_team_record​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/record

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/record

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.

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: ESPN answers an empty object 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​

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_ucl_team_record(team_id='4')

espn_ucl_team_depthcharts​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/depthcharts

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/depthcharts

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.

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: depthchart, season, status, team, timestamp).

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_ucl_team_depthcharts(team_id='4')

espn_ucl_team_injuries​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/injuries

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/injuries

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_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_nametypedescription
idInt64ESPN numeric identifier for the athlete.
display_nameStringAthlete's full display name as shown on ESPN.
injuriesStringInjury entries for the athlete (list of dicts, stringified): status, type, details, dates.

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_ucl_team_injuries(team_id='4')

espn_ucl_team_transactions​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/transactions

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/transactions

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.

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: ESPN answers an empty object 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​

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_ucl_team_transactions(team_id='4')

espn_ucl_team_history​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/history

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/history

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.

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: ESPN answers an empty object in nba, nfl, mlb, nhl, wnba, mbb, wbb; 400 in cfb with the documented example arguments (2026-10-07).

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_ucl_team_history(team_id='4')

espn_ucl_team_news​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/news

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/news?limit=50

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
limitlimitYMaximum 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_nametypedescription
idInt64ESPN numeric identifier for the article.
now_idStringESPN 'now' feed id.
content_keyStringInternal content key.
data_source_identifierStringSource-system identifier.
typeStringArticle type (Story, Media, HeadlineNews, etc.).
headlineStringArticle headline.
descriptionStringArticle summary/description.
last_modifiedStringLast-modified timestamp (ISO 8601).
publishedStringPublish timestamp (ISO 8601).
imagesStringArticle images (list, stringified).
categoriesStringArticle categories (list, stringified).
premiumBooleanWhether the article is premium/paywalled.
bylineStringAuthor byline string as published by ESPN.
links_web_hrefStringWeb article URL.
links_mobile_hrefStringMobile article URL.
links_api_self_hrefStringESPN API canonical self-link for the article resource.
links_app_sportscenter_hrefStringSportsCenter app deep link.

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_ucl_team_news(team_id='4')

espn_ucl_team_leaders​

Deprecated: ESPN answers this team route with an empty object.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/{team_id}/leaders

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/teams/4/leaders

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.

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: ESPN answers an empty object 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​

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_ucl_team_leaders(team_id='4')

espn_ucl_player_info​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/{athlete_id}

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/4239

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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​

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

espn_ucl_player_bio​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/{athlete_id}/bio

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/4239/bio

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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​

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

espn_ucl_player_news​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/{athlete_id}/news

Valid URL: https://site.api.espn.com/apis/site/v2/sports/soccer/uefa.champions/athletes/4239/news

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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_nametypedescription
idInt64ESPN numeric identifier for the article.
now_idStringESPN 'now' feed id.
content_keyStringInternal content key.
data_source_identifierStringSource-system identifier.
typeStringArticle type (Story, Media, HeadlineNews, etc.).
headlineStringArticle headline.
descriptionStringArticle summary/description.
last_modifiedStringLast-modified timestamp (ISO 8601).
publishedStringPublish timestamp (ISO 8601).
imagesStringArticle images (list, stringified).
categoriesStringArticle categories (list, stringified).
premiumBooleanWhether the article is premium/paywalled.
bylineStringAuthor byline string as published by ESPN.
links_web_hrefStringWeb article URL.
links_mobile_hrefStringMobile article URL.
links_api_self_hrefStringESPN API canonical self-link for the article resource.
links_app_sportscenter_hrefStringSportsCenter app deep link.

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

espn_ucl_standings​

ESPN endpoint.

Endpoint URL: GET https://site.api.espn.com/apis/v2/sports/soccer/uefa.champions/standings

Valid URL: https://site.api.espn.com/apis/v2/sports/soccer/uefa.champions/standings

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
groupgroupYConference or group id filter (e.g. an ESPN conference id).
typestandings_typeYStandings 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_nametypedescription
groupStringConference/group/table the row belongs to, flattened from the standings children hierarchy.
teamStringDisplay name of the team in this standings row.
team_idStringESPN numeric identifier for the team.
team_abbreviationStringTeam abbreviation.
noteStringStandings note (e.g. qualification/relegation marker).
games_playedFloat64Matches played.
lossesFloat64Number of matches the team has lost.
point_differentialFloat64Goal difference (for minus against).
pointsFloat64Competition points.
points_againstFloat64Goals conceded.
points_forFloat64Goals (or runs) scored by the team.
tiesFloat64Number of matches the team has drawn.
winsFloat64Number of matches the team has won.
advancedFloat64Whether the team has advanced/qualified.
deductionsFloat64Points deducted.
ppgFloat64Points per game.
rankFloat64Position within the group/table.
rank_changeFloat64Change in rank versus the previous update.
overallStringOverall record summary as published by ESPN.

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