Skip to main content

NWSL — ESPN web API (v3)

sportsdataverse.soccer.nwsl — 5 endpoints.

espn_nwsl_player_overview​

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/{athlete_id}/overview

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/4239/overview

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
athlete_idInt64
athlete_display_nameString
athlete_short_nameString
athlete_positionString
athlete_jerseyString
athlete_team_idInt64
athlete_team_abbreviationString
split_nameString
split_categoryString
games_playedString
avg_minutesString
field_goal_pctString
three_point_pctString
free_throw_pctString
avg_reboundsString
avg_assistsString
avg_blocksString
avg_stealsString
avg_foulsString
avg_turnoversString
avg_pointsString

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

espn_nwsl_player_stats​

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/{athlete_id}/stats

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/4239/stats

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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
categoryStringESPN stat category the row belongs to (e.g., basketball "averages" / "totals" / "miscellaneous", NFL "passing", MLB "career-batting"). The stat columns after position are named from each category's own names list, so they differ by sport, and the other categories' columns are null on a row.
split_nameStringSeason label of the row (e.g., "2010-11") on the Web v3 payload, or "Career" on the row built from the category's career totals; the split's name on payloads that ship named splits.
split_categoryStringCategory of a named split; null on the Web v3 per-season rows.
split_valueStringValue of a named split; null on the Web v3 per-season rows.
seasonInt64Season end year of the row (e.g., 2011 for 2010-11); null on the "Career" row.
team_idInt64ESPN team id (Int64) the athlete played that season for; a traded player has one row per team. Null on the "Career" row.
positionStringPosition abbreviation the athlete was listed at for that season and team (e.g., "G"); null on the "Career" row.

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

espn_nwsl_player_gamelog​

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/{athlete_id}/gamelog

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/4239/gamelog

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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
season_type_idInt64ESPN season type of the row (2 regular season, 3 postseason).
season_type_nameStringSeason type's name as ESPN ships it (e.g., "2019-20 Regular Season").
categoryStringSplit the row was listed under; on the Web v3 payload a month (e.g., "january").
event_idInt64ESPN event (game) id (Int64), the key the game endpoints take.
event_dateStringScheduled game start, ISO 8601 UTC as ESPN ships it.
home_awayStringThe athlete's side, "home" or "away", from which side the opponent was on; null when ESPN names neither.
scoreStringFinal score as ESPN prints it, winner first (e.g., "123-115").
opponent_idInt64ESPN team id (Int64) of the opponent.
opponent_abbreviationStringOpponent's abbreviation (e.g., "BOS").
opponent_display_nameStringOpponent's full name (e.g., "Boston Celtics").
game_resultStringThe athlete's team result, "W" or "L" (or "T").
game_processedStringWhether ESPN has finished processing the game's stats.
minutesStringMinutes played, a whole-number string as ESPN ships it (e.g., "21"). The stat columns from here on are named from the payload's own stat names, so they differ by sport, and every value is a string.
field_goals_made_field_goals_attemptedStringField goals made-attempted, a "made-attempted" string (e.g., "1-4").
field_goal_pctStringField-goal percentage on a 0-100 scale, as a string (e.g., "25.0").
three_point_field_goals_made_three_point_field_goals_attemptedStringThree-pointers made-attempted, a "made-attempted" string (e.g., "0-2").
three_point_pctStringThree-point percentage on a 0-100 scale, as a string.
free_throws_made_free_throws_attemptedStringFree throws made-attempted, a "made-attempted" string.
free_throw_pctStringFree-throw percentage on a 0-100 scale, as a string.
total_reboundsStringTotal rebounds in the game.
assistsStringAssists in the game.
blocksStringBlocked shots in the game.
stealsStringSteals in the game.
foulsStringPersonal fouls in the game.
turnoversStringTurnovers in the game.
pointsStringPoints the athlete scored in the game.

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

espn_nwsl_player_splits​

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/{athlete_id}/splits

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/athletes/4239/splits

API ParameterPythonPatternRequiredNullableDescription
athlete_idathlete_idYathlete_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
descriptionsString
display_nameString
display_namesString
filtersString
labelsString
namesString
split_categoriesString

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

espn_nwsl_leaders​

ESPN endpoint.

Endpoint URL: GET https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/statistics/byathlete

Valid URL: https://site.web.api.espn.com/apis/common/v3/sports/soccer/usa.nwsl/statistics/byathlete?limit=50&page=1

API ParameterPythonPatternRequiredNullableDescription
categorycategoryYLeaderboard population: the athletes ranked in that category, whose values it fills (other categories come back null). Football takes <group>:<category> (offense:passing, offense:rushing, offense:receiving, defense:defensive, scoring:scoring); a bare passing is rejected with HTTP 400 (ValueError). Basketball takes the bare name (offensive).
seasonseasonYSeason year (e.g. 2024).
seasontypeseason_typeYSeason phase: 1=preseason, 2=regular season, 3=postseason.
limitlimitYMaximum number of items to return.
pagepageYpage query parameter.
sortsortYSort key <category>.<statName>:<asc|desc>, the names in the payload's categories (passing.passingYards:desc, offensive.avgPoints:desc). A stat without its category is rejected with HTTP 400 (ValueError).

Returns​

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

col_nametypedescription
sort_orderInt64Position of the athlete in ESPN's leaderboard order (the requested category or sort), counted across pages: (page - 1) * limit + position on the page. A position, not a rank: tied athletes still count up; ESPN's per-stat ranks stay in the raw payload (return_parsed=False).
athlete_idInt64ESPN id of the athlete, the key the athlete endpoints (athlete_overview, athlete_stats) take.
athlete_uidStringESPN composite athlete uid (s:<sport>~l:<league>~a:<athlete id>), kept as text.
athlete_display_nameStringAthlete's full display name.
athlete_short_nameStringAthlete's abbreviated name (e.g. 'B. Nix').
athlete_first_nameStringAthlete's first name.
athlete_last_nameStringAthlete's last name.
athlete_positionStringAthlete's position abbreviation (e.g. QB, G, C).
athlete_statusStringAthlete's ESPN status name (e.g. Active, Inactive) as ESPN reports it at request time, not for the requested season.
team_idInt64ESPN id of the team the athlete played for in the requested season.
team_abbreviationStringAbbreviation of the athlete's team in the requested season (ESPN teamShortName, e.g. ORE).
team_nameStringNickname of the athlete's team in the requested season (ESPN teamName, e.g. Ducks).

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