Skip to main content

Soccer (all) — American Soccer Analysis (app.americansocceranalysis.com)

sportsdataverse.soccer — 16 endpoints.

asa_games​

Games/fixtures with final scores, venue/official/manager FKs.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/games

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/games

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

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_idStringASA game id (base62 string; Utf8 join key).
date_time_utcStringKickoff timestamp (UTC, ISO 8601).
home_scoreInt64Home goals (regulation + extra time).
away_scoreInt64Away goals (regulation + extra time).
home_team_idStringFK -> Team (home side).
away_team_idStringFK -> Team (away side).
referee_idStringASA referee id (base62 string; Utf8 join key).
stadium_idStringASA stadium id (base62 string; Utf8 join key).
home_manager_idStringFK -> Manager (home side; nullable).
away_manager_idStringFK -> Manager (away side; nullable).
expanded_minutesInt64Total match minutes incl. stoppage (data coverage window).
season_nameStringSeason(s) the player appears in; may serialize as a scalar, a list, or an object across the leagues.
matchdayInt64Round/matchday number.
knockout_gameBooleanTrue if a knockout/playoff fixture.
statusStringGame status (e.g. final).
last_updated_utcStringLast-updated timestamp (UTC, ISO 8601).
attendanceInt64Reported attendance (nullable).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_games(league_slug='mls')

asa_games_xgoals​

Per-game expected-goals + expected points for both sides.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/games/xgoals

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/games/xgoals

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

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_idStringASA game id (base62 string; Utf8 join key).
date_time_utcStringKickoff timestamp (UTC, ISO 8601).
home_team_idStringFK -> Team (home side).
home_goalsInt64Home goals scored.
home_team_xgoalsFloat64Home expected goals (team model).
home_player_xgoalsFloat64Home expected goals (player-shot model).
away_team_idStringFK -> Team (away side).
away_goalsInt64Away goals scored.
away_team_xgoalsFloat64Away expected goals (team model).
away_player_xgoalsFloat64Away expected goals (player-shot model).
goal_differenceInt64goals_for - goals_against.
team_xgoal_differenceFloat64Home minus away team xGoals.
player_xgoal_differenceFloat64Home minus away player xGoals.
final_score_differenceInt64Final goal margin (home perspective).
home_xpointsFloat64Home expected points from the match.
away_xpointsFloat64Away expected points from the match.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_games_xgoals(league_slug='mls')

asa_goalkeepers_goals_added​

Per-goalkeeper Goals Added with a per-action-type data[] breakdown.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/goalkeepers/goals-added

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/goalkeepers/goals-added

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns empty summary and actions frames. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
minutes_playedInt64Minutes played in the filtered window.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_goalkeepers_goals_added(league_slug='mls')

asa_goalkeepers_xgoals​

Per-goalkeeper shot-stopping vs post-shot expected goals.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/goalkeepers/xgoals

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/goalkeepers/xgoals

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
minutes_playedInt64Minutes played in the filtered window.
shots_facedInt64Shots faced.
goals_concededInt64Goals conceded.
savesInt64Saves made.
share_headed_shotsFloat64Share of faced shots that were headers.
xgoals_gk_facedFloat64Post-shot expected goals faced.
goals_minus_xgoals_gkFloat64Goals conceded minus post-shot xG (negative = shots saved above expectation).
goals_divided_by_xgoals_gkFloat64Goals conceded / post-shot xG faced.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_goalkeepers_xgoals(league_slug='mls')

asa_managers​

Managers/head coaches.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/managers

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/managers

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

Returns​

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

col_nametypedescription
manager_idStringASA manager id (base62 string; Utf8 join key).
manager_nameStringManager display name.
nationalityStringPlayer nationality (country name).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_managers(league_slug='mls')

asa_players​

Players in the league (identity + biometrics + positions).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/players

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/players

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
player_nameStringPlayer display name.
birth_dateStringDate of birth (YYYY-MM-DD; may be null).
height_ftInt64Listed height, feet component.
height_inInt64Listed height, inches component.
weight_lbInt64Listed weight in pounds.
nationalityStringPlayer nationality (country name).
primary_broad_positionStringBroad position bucket (Goalkeeper/Defender/Midfielder/Forward).
primary_general_positionStringGeneral position code (GK/CB/FB/DM/CM/AM/W/ST).
season_nameStringSeason(s) the player appears in; may serialize as a scalar, a list, or an object across the leagues.
secondary_general_positionStringSecondary general position code (nullable).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_players(league_slug='mls')

asa_players_goals_added​

Per-player Goals Added (g+) with a per-action-type data[] breakdown.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/players/goals-added

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/players/goals-added

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns empty summary and actions frames. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
general_positionStringGeneral position code (GK/CB/FB/DM/CM/AM/W/ST).
minutes_playedInt64Minutes played in the filtered window.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_players_goals_added(league_slug='mls')

asa_players_salaries​

Player salaries (MLS only; server caps the response at 10000 rows).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/players/salaries

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/players/salaries

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
season_nameInt64Season(s) the player appears in; may serialize as a scalar, a list, or an object across the leagues.
positionStringRoster position designation (string; distinct from general_position).
base_salaryInt64Base salary (USD).
guaranteed_compensationInt64Guaranteed compensation (USD).
mlspa_releaseStringMLSPA salary-release label/date the row is sourced from.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_players_salaries(league_slug='mls')

asa_players_xgoals​

Per-player expected-goals + attacking production.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/players/xgoals

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/players/xgoals

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
general_positionStringGeneral position code (GK/CB/FB/DM/CM/AM/W/ST).
minutes_playedInt64Minutes played in the filtered window.
shotsInt64Shots taken.
shots_on_targetInt64Shots on target.
goalsInt64Goals scored.
xgoalsFloat64Expected goals (pre-shot xG).
xplaceFloat64Expected goals added by shot placement (post-shot minus pre-shot).
goals_minus_xgoalsFloat64Finishing over expectation (goals - xG).
key_passesInt64Passes that led to a shot.
primary_assistsInt64Primary assists.
xassistsFloat64Expected assists.
primary_assists_minus_xassistsFloat64Assists over expectation.
goals_plus_primary_assistsInt64Goals + primary assists (G+A).
xgoals_plus_xassistsFloat64xGoals + xAssists (xG+xA).
points_addedFloat64Team points added by the player's attacking output.
xpoints_addedFloat64Expected team points added.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_players_xgoals(league_slug='mls')

asa_players_xpass​

Per-player expected-passing (completion over expected, distance, share of team touches).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/players/xpass

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/players/xpass

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

Returns​

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

col_nametypedescription
player_idStringASA player id (base62 string; Utf8 join key).
team_idStringASA team id (base62 string; Utf8 join key, never numeric).
general_positionStringGeneral position code (GK/CB/FB/DM/CM/AM/W/ST).
minutes_playedInt64Minutes played in the filtered window.
attempted_passesInt64Passes attempted.
pass_completion_percentageFloat64Actual pass completion (0-1).
xpass_completion_percentageFloat64Expected pass completion (0-1).
passes_completed_over_expectedFloat64Passes completed over expected.
passes_completed_over_expected_p100Float64Passes completed over expected per 100 passes.
avg_distance_ydsFloat64Average pass distance in yards.
avg_vertical_distance_ydsFloat64Average vertical (goalward) pass distance in yards.
share_team_touchesFloat64Share of the team's touches (0-1).
count_gamesInt64Games included in the window.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_players_xpass(league_slug='mls')

asa_referees​

Match referees.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/referees

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/referees

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

Returns​

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

col_nametypedescription
referee_idStringASA referee id (base62 string; Utf8 join key).
referee_nameStringReferee display name.
birth_dateStringDate of birth (YYYY-MM-DD; may be null).
nationalityStringPlayer nationality (country name).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_referees(league_slug='mls')

asa_stadia​

Stadia (venue metadata incl. coordinates + pitch dimensions).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/stadia

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/stadia

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

Returns​

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

col_nametypedescription
stadium_idStringASA stadium id (base62 string; Utf8 join key).
stadium_nameStringVenue name.
capacityInt64Seating capacity.
year_builtInt64Year the venue opened.
roofBooleanWhether the venue has a roof.
turfBooleanWhether the playing surface is artificial turf.
streetStringStreet address.
cityStringCity.
provinceStringState/province.
countryStringCountry.
postal_codeStringPostal/ZIP code.
latitudeFloat64Latitude (decimal degrees).
longitudeFloat64Longitude (decimal degrees).
field_xInt64Pitch length (venue-reported field dimension).
field_yInt64Pitch width (venue-reported field dimension).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_stadia(league_slug='mls')

asa_teams​

Teams in the league (full table, no filter params).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/teams

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/teams

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").

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_idStringASA team id (base62 string; Utf8 join key, never numeric).
team_nameStringFull club name.
team_short_nameStringShort club name.
team_abbreviationStringShort (2-4 char) club abbreviation.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_teams(league_slug='mls')

asa_teams_goals_added​

Per-team Goals Added for/against with a per-action-type data[] breakdown.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/teams/goals-added

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/teams/goals-added

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns empty summary and actions frames. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

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_idStringASA team id (base62 string; Utf8 join key, never numeric).
minutesInt64Team minutes in the window.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_teams_goals_added(league_slug='mls')

asa_teams_xgoals​

Per-team expected-goals for/against + expected points.

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/teams/xgoals

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/teams/xgoals

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

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_idStringASA team id (base62 string; Utf8 join key, never numeric).
count_gamesInt64Games included in the window.
shots_forInt64Shots taken.
shots_againstInt64Shots faced.
goals_forInt64Goals scored.
goals_againstInt64Goals conceded.
goal_differenceInt64goals_for - goals_against.
xgoals_forFloat64Expected goals created.
xgoals_againstFloat64Expected goals conceded.
xgoal_differenceFloat64xgoals_for - xgoals_against.
goal_difference_minus_xgoal_differenceFloat64Finishing/keeping over expectation.
pointsInt64Actual league points earned.
xpointsFloat64Expected league points.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_teams_xgoals(league_slug='mls')

asa_teams_xpass​

Per-team expected-passing (completion over expected, vertical distance).

Endpoint URL: GET https://app.americansocceranalysis.com/api/v1/{league_slug}/teams/xpass

Valid URL: https://app.americansocceranalysis.com/api/v1/mls/teams/xpass

API ParameterPythonPatternRequiredNullableDescription
league_slugleague_slugYASA league slug: mls (2013+), nwsl (2016+), uslc (2017+), usl1 (2019+), mlsnp (2022+), nasl (2017 only) or usls. A season before the league floor returns an empty frame. USL Super League seasons use split-year labels (season_name="2024-25").
season_nameseason_nameYFilter to one or more seasons. Comma-list accepted (2022,2023).
stage_namestage_nameYFilter to a competition stage, e.g. Regular Season. URL-encode spaces.
minimum_minutesminimum_minutesYDrop players/teams below this minutes-played threshold.
general_positiongeneral_positionYFilter by general position code: GK, CB, FB, DM, CM, AM, W, ST (player/GK routes).
split_by_teamssplit_by_teamsYtrue => one row per entity per team (splits traded players).
split_by_seasonssplit_by_seasonsYtrue => one row per entity per season.
split_by_gamessplit_by_gamesYtrue => one row per entity per game.
start_datestart_dateYLower date bound (YYYY-MM-DD), where the route supports date windows.
end_dateend_dateYUpper date bound (YYYY-MM-DD), where the route supports date windows.

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_idStringASA team id (base62 string; Utf8 join key, never numeric).
count_gamesInt64Games included in the window.
attempted_passes_forInt64Passes attempted by the team.
pass_completion_percentage_forFloat64Actual pass completion % (for).
xpass_completion_percentage_forFloat64Expected pass completion % (for).
passes_completed_over_expected_forFloat64Passes completed over expected (for).
passes_completed_over_expected_p100_forFloat64Passes completed over expected per 100 passes (for).
avg_vertical_distance_forFloat64Average vertical (goalward) pass distance (for).
attempted_passes_againstInt64Passes attempted by opponents.
pass_completion_percentage_againstFloat64Actual pass completion % (against).
xpass_completion_percentage_againstFloat64Expected pass completion % (against).
passes_completed_over_expected_againstFloat64Passes completed over expected (against).
passes_completed_over_expected_p100_againstFloat64Passes completed over expected per 100 passes (against).
avg_vertical_distance_againstFloat64Average vertical pass distance (against).
passes_completed_over_expected_differenceFloat64For minus against (passes over expected).
avg_vertical_distance_differenceFloat64For minus against (vertical distance).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The ASA API returned 404 (route not published for that league).
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​

asa_teams_xpass(league_slug='mls')