### Install Development Version Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Clone the repository and install in editable mode with development dependencies. ```bash git clone https://github.com/American-Soccer-Analysis/itscalledsoccer.git cd itscalledsoccer pip install -e ".[dev]" ``` -------------------------------- ### Install development dependencies Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Use uv to install project dependencies and create a virtual environment. ```sh uv sync --all-extras --dev ``` -------------------------------- ### Verify git installation Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Check that git is installed correctly. ```sh git -v ``` -------------------------------- ### Verify uv installation Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Check that uv is installed correctly. ```sh uv --help ``` -------------------------------- ### Installation Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Install the stable release of the itscalledsoccer package via pip, or install the development version from the GitHub repository. ```APIDOC ## Installation ### Stable Release ```bash pip install itscalledsoccer ``` ### Development Version ```bash git clone https://github.com/American-Soccer-Analysis/itscalledsoccer.git cd itscalledsoccer pip install -e ".[dev]" ``` **Requirements:** Python 3.10+, `requests`, `polars`, `cachecontrol`, `pydantic` ``` -------------------------------- ### Example usage of get_player_goals_added Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md An example showing how to initialize the client and fetch goals-added data for specific leagues and action types. ```python asa = AmericanSoccerAnalysis() gplus = asa.get_player_goals_added( leagues="uslc", above_replacement=True, action_type=["Passing", "Shooting"], ) ``` -------------------------------- ### Install itscalledsoccer with pip Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/docs/index.md Install the stable release of itscalledsoccer from PyPI using pip. ```sh pip install itscalledsoccer ``` -------------------------------- ### Install Commitizen and pre-commit hooks Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Commands to install the necessary tools and initialize the pre-commit hook for commit message validation after cloning the repository. ```sh uv tool install commitizen uv tool install pre-commit pre-commit install --hook-type commit-msg ``` -------------------------------- ### Quick Start Client Initialization Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Initialize the AmericanSoccerAnalysis client and retrieve player or xG data. ```python from itscalledsoccer import AmericanSoccerAnalysis # Initialize client (no authentication required) asa = AmericanSoccerAnalysis() # Get all USLC players uslc_players = asa.get_players(leagues="uslc") # Get Expected Goals (xG) data for 2023 xg_data = asa.get_player_xgoals( leagues="uslc", season_name="2023" ) ``` -------------------------------- ### get_goalkeeper_xgoals example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Example usage of get_goalkeeper_xgoals to filter by league, minimum minutes, and minimum shots faced. ```python asa = AmericanSoccerAnalysis() gk_xg = asa.get_goalkeeper_xgoals( leagues="nwsl", minimum_minutes=1800, minimum_shots_faced=200, ) ``` -------------------------------- ### Initialize Eager Loading Client with Custom Configuration Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md Example of initializing the client with eager loading, custom proxy settings, DEBUG logging, and a 60-second timeout. ```python asa = AmericanSoccerAnalysis( proxies={"http": "http://proxy.local:8080", "https": "https://proxy.local:8080"}, logging_level="DEBUG", lazy_load=False, # fetch all entity tables at startup request_timeout=60, ) print(asa.players.shape) # already populated ``` -------------------------------- ### Basic get_games example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Example of calling get_games with a single league, season, and team name. The result is a DataFrame of games. ```python asa = AmericanSoccerAnalysis() games = asa.get_games(leagues="uslc", seasons="2024", team_names="Louisville City") ``` -------------------------------- ### Verify Python installation Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Commands to confirm that Python is available on your system. ```sh python --version # Or: python3 --version # On Windows (cmd.exe, with the Python Launcher for Windows): py --version ``` -------------------------------- ### get_team_salaries usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Example of calling get_team_salaries for the 2024 MLS season. ```python asa = AmericanSoccerAnalysis() team_salaries = asa.get_team_salaries(leagues="mls", split_by_teams=True, season_name="2024") ``` -------------------------------- ### Initialize Default AmericanSoccerAnalysis Client Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md Example of initializing the client with default settings, which enables lazy loading, WARNING logging, and a 30-second timeout. ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() # lazy loading, WARNING logging, 30s timeout xg = asa.get_player_xgoals(leagues="uslc", season_name="2023") ``` -------------------------------- ### get_stadia usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Example usage of get_stadia. Fetches stadiums with names matching 'PNC'. ```python asa = AmericanSoccerAnalysis() stadia = asa.get_stadia(names="PNC") ``` -------------------------------- ### Example usage of get_team_xgoals Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Demonstrates how to initialize the AmericanSoccerAnalysis client and retrieve team xGoals for the USLC league with specific filters applied. ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() team_xg = asa.get_team_xgoals( leagues="uslc", split_by_seasons=True, home_only=True, even_game_state=True, ) ``` -------------------------------- ### Example usage of get_game_xgoals Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Demonstrates how to initialize the client and retrieve xGoals data for specific MLS games in the 2024 season. ```python asa = AmericanSoccerAnalysis() game_xg = asa.get_game_xgoals( leagues="mls", game_ids=["Vj58m7jEq8", "2lqRG7bDQr"], season_name="2024", ) ``` -------------------------------- ### get_managers usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Shows how to call get_managers with a league code and a manager name filter. ```python asa = AmericanSoccerAnalysis() managers = asa.get_managers(leagues="uslc", names="Valentino") ``` -------------------------------- ### Conventional Commit message examples Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Examples of valid commit messages including feature, fix, and documentation types with optional issue references. ```text feat: add substring name matching (#123) fix(client): handle empty entity names (#456) docs: clarify installation requirements ``` -------------------------------- ### Install development version with pip editable Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/docs/index.md Install a development version of itscalledsoccer from a cloned repository using pip's editable mode. ```sh pip install --editable . ``` -------------------------------- ### get_team_goals_added usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Example of calling get_team_goals_added with specific league, zone, gamestate, and season splitting parameters. ```python asa = AmericanSoccerAnalysis() team_gplus = asa.get_team_goals_added( leagues="mls", zone=[5, 6, 7], gamestate_trunc=0, split_by_seasons=True, ) ``` -------------------------------- ### get_referees usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Shows how to call get_referees with a list of league codes and a referee name filter. ```python asa = AmericanSoccerAnalysis() referees = asa.get_referees(leagues=["uslc", "mls"], names="Kelly") ``` -------------------------------- ### get_goalkeeper_goals_added example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Example usage of get_goalkeeper_goals_added to retrieve MLS data aggregated above replacement level and split by season. ```python asa = AmericanSoccerAnalysis() gk_gplus = asa.get_goalkeeper_goals_added( leagues="mls", above_replacement=True, split_by_seasons=True, ) ``` -------------------------------- ### SeasonParameters Direct Usage Example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/validation.md Demonstrates initializing SeasonParameters with valid input and handling an InvalidSeasonError for years prior to 2013. ```python from itscalledsoccer.validation import SeasonParameters from itscalledsoccer.errors import InvalidSeasonError result = SeasonParameters.model_validate({"season_name": [2023, "2024"]}).season_name assert result == ["2023", "2024"] try: SeasonParameters.model_validate({"season_name": 2012}) except InvalidSeasonError as e: print(e) # "Data is only available from 2013 onward. Requested season: 2012" ``` -------------------------------- ### get_teams usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Example usage of get_teams. Fetches teams filtered by league codes 'uslc' and 'nwsl', and then fetches teams in the 'mls' league with names matching 'LA'. ```python asa = AmericanSoccerAnalysis() teams = asa.get_teams(leagues=["uslc", "nwsl"]) la_teams = asa.get_teams(leagues="mls", names="LA") ``` -------------------------------- ### get_players usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Basic usage of get_players to retrieve players by league or by name using substring matching. ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() uslc_players = asa.get_players(leagues="uslc") vela = asa.get_players(names="Carlos Vela") # substring match ``` -------------------------------- ### get_player_salaries usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Retrieves salary data for forwards and midfielders in the 2023 MLS season. ```python asa = AmericanSoccerAnalysis() salaries = asa.get_player_salaries(leagues="mls", season_name="2023", position=["F", "M"]) ``` -------------------------------- ### get_players error handling Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Example demonstrating how to catch InvalidLeagueError when providing an invalid league code. ```python from itscalledsoccer import AmericanSoccerAnalysis, InvalidLeagueError asa = AmericanSoccerAnalysis() try: asa.get_players(leagues="nope", ids="bad-id") except InvalidLeagueError as e: print(f"Bad league: {e}") # "nope is not valid. Must be one of: [...]" ``` -------------------------------- ### Example usage of get_player_xpass Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Retrieves xPass data for players in the USLC with at least 900 minutes played, filtered by attacking third passes and split by season. ```python asa = AmericanSoccerAnalysis() xpass = asa.get_player_xpass( leagues="uslc", minimum_minutes=900, pass_origin_third="Attacking", split_by_seasons=True, ) ``` -------------------------------- ### get_player_xgoals usage example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Retrieves player expected goals for the USLC 2025 season, filtered by a minimum of 900 minutes and specific shot patterns. ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() xg = asa.get_player_xgoals( leagues="uslc", season_name="2025", minimum_minutes=900, shot_pattern=["Set piece", "Penalty"], ) ``` -------------------------------- ### get_team_salaries error handling example Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Demonstrates handling the SalaryDataError when requesting non-MLS salary data. ```python from itscalledsoccer import AmericanSoccerAnalysis, SalaryDataError asa = AmericanSoccerAnalysis() try: asa.get_team_salaries(leagues="uslc") except SalaryDataError as e: print(e) # "Only MLS salary data is publicly available." ``` -------------------------------- ### _single_request(url, params) method Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md Performs a single HTTP GET request using the provided session, raises an exception for non-2xx responses, and converts the JSON response to a DataFrame. ```python def _single_request( self, url: str, params: dict[str, str | list[str] | None] ) -> pl.DataFrame: ``` -------------------------------- ### Retrieve team xpass statistics Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md Example usage of get_team_xpass to fetch data for specific leagues, split by seasons, and filtered by the attacking third. ```python asa = AmericanSoccerAnalysis() team_xpass = asa.get_team_xpass( leagues=["uslc", "nwsl"], split_by_seasons=True, pass_origin_third="Attacking", ) ``` -------------------------------- ### Handle ConflictingParametersError Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/validation.md Example of catching a ConflictingParametersError when both mutually exclusive parameters are provided to the QueryParameters model. ```python from itscalledsoccer.validation import QueryParameters from itscalledsoccer.errors import ConflictingParametersError try: QueryParameters(ids="i1", names="Vela") except ConflictingParametersError as e: print(e) # "Please specify only IDs or names, not both." ``` -------------------------------- ### Get players by name with get_players Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/docs/index.md Retrieve all players named 'Andre' using the get_players method. Partial matches or abbreviations are accepted for player names, and arguments must be named for most methods. ```python # Get all players named "Andre" asa_players = asa_client.get_players(names="Andre") ``` -------------------------------- ### get_games with multiple filters and error handling Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md Example using multiple filters (leagues, season_name, status, stages) and catching InvalidSeasonError. The returned DataFrame is already sorted by date_time_utc descending. ```python try: games = asa.get_games( leagues=["mls", "nwsl"], season_name=[2023, 2024], status="FullTime", stages="Regular", ) except InvalidSeasonError as e: print(e) # "Data is only available from 2013 onward. Requested season: ..." games_sorted = games.sort("date_time_utc", descending=True) # already sorted by the method ``` -------------------------------- ### GET {base_url}{league}/{entity}/{stat_type} Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/endpoints.md Retrieves statistics for a specified entity (players, goalkeepers, teams, games) and stat type (xgoals, xpass, goals-added, salaries). The endpoint is constructed by the client's _get_stats method and supports various query parameters for filtering and pagination. ```APIDOC ## GET {base_url}{league}/{entity}/{stat_type} ### Description Retrieves statistics for a specified entity (players, goalkeepers, teams, games) and stat type (xgoals, xpass, goals-added, salaries). The endpoint is constructed by the client's _get_stats method and supports various query parameters for filtering and pagination. ### Method GET ### Endpoint {base_url}{league}/{entity}/{stat_type} ### Parameters #### Path Parameters - **league** (string) - Required - League identifier (e.g., uslc) - **entity** (string) - Required - Entity type: players, goalkeepers, teams, games - **stat_type** (string) - Required - Statistic type: xgoals, xpass, goals-added, salaries #### Query Parameters - **player_id** (string) - Optional - Player ID or comma-joined list of player IDs - **team_id** (string) - Optional - Team ID or comma-joined list of team IDs - **game_id** (string) - Optional - Game ID or comma-joined list of game IDs - **season_name** (string) - Optional - Season name or comma-joined list of season names - **start_date** (string) - Optional - Start date in YYYY-MM-DD format - **end_date** (string) - Optional - End date in YYYY-MM-DD format - **minimum_minutes** (integer) - Optional - Minimum minutes played - **minimum_shots** (integer) - Optional - Minimum shots (method-specific) - **minimum_key_passes** (integer) - Optional - Minimum key passes (method-specific) - **minimum_passes** (integer) - Optional - Minimum passes (method-specific) - **minimum_shots_faced** (integer) - Optional - Minimum shots faced (method-specific) - **shot_pattern** (string) - Optional - Shot pattern or comma-joined list - **pass_origin_third** (string) - Optional - Pass origin third or comma-joined list - **action_type** (string) - Optional - Action type or comma-joined list - **general_position** (string) - Optional - General position or comma-joined list - **position** (string) - Optional - Position or comma-joined list - **stage_name** (string) - Optional - Stage name or comma-joined list - **split_by_teams** (boolean) - Optional - Split results by teams (true/false) - **split_by_seasons** (boolean) - Optional - Split results by seasons (true/false) - **split_by_games** (boolean) - Optional - Split results by games (true/false) - **split_by_positions** (boolean) - Optional - Split results by positions (true/false) - **home_only** (boolean) - Optional - Only home games (true/false) - **away_only** (boolean) - Optional - Only away games (true/false) - **home_adjusted** (boolean) - Optional - Home adjusted (true/false) - **even_game_state** (boolean) - Optional - Even game state (true/false) - **above_replacement** (boolean) - Optional - Above replacement (true/false) - **zone** (integer) - Optional - Zone or comma-joined list (team goals-added) - **gamestate_trunc** (integer) - Optional - Game state truncation or comma-joined list (team goals-added) - **offset** (integer) - Optional - Pagination offset (1000, 2000, ...) automatically added when page has exactly 1000 rows ### Request Example GET https://app.americansocceranalysis.com/api/v1/uslc/players/xgoals?season_name=2023&minimum_minutes=900&split_by_teams=true ### Response #### Success Response (200) Response fields vary by entity and stat type. See below for field lists. #### Response Example For players/xgoals: { "player_id": "string", "team_id": "string", "general_position": "string", "minutes_played": "integer", "shots": "integer", "shots_on_target": "integer", "goals": "integer", "xgoals": "number", "xplace": "number", "goals_minus_xgoals": "number", "key_passes": "integer", "primary_assists": "integer", "xassists": "number", "primary_assists_minus_xassists": "number", "xgoals_plus_xassists": "number", "points_added": "number", "xpoints_added": "number" } ### Response Fields by Endpoint **players/xgoals:** player_id, team_id, general_position, minutes_played, shots, shots_on_target, goals, xgoals, xplace, goals_minus_xgoals, key_passes, primary_assists, xassists, primary_assists_minus_xassists, xgoals_plus_xassists, points_added, xpoints_added **players/xpass:** player_id, team_id, general_position, minutes_played, attempted_passes, pass_completion_percentage, xpass_completion_percentage, passes_completed_over_expected, passes_completed_over_expected_p100, avg_distance_yds, avg_vertical_distance_yds, share_team_touches, count_games **players/goals-added:** player_id, team_id, general_position, minutes_played, data (nested per-action records) **players/salaries:** player_id, team_id, season_name, position, base_salary, guaranteed_compensation, mlspa_release **goalkeepers/xgoals:** player_id, team_id, minutes_played, shots_faced, goals_conceded, saves, share_headed_shots, xgoals_gk_faced, goals_minus_xgoals_gk, goals_divided_by_xgoals_gk **goalkeepers/goals-added:** player_id, team_id, minutes_played, data **teams/xgoals:** team_id, count_games, shots_for, shots_against, goals_for, goals_against, goal_difference, xgoals_for, xgoals_against, xgoal_difference, goal_difference_minus_xgoal_difference, points, xpoints **teams/xpass:** team_id, count_games, attempted_passes_for, pass_completion_percentage_for, xpass_completion_percentage_for, passes_completed_over_expected_for, passes_completed_over_expected_p100_for, avg_vertical_distance_for, attempted_passes_against, pass_completion_percentage_against, xpass_completion_percentage_against, passes_completed_over_expected_against, passes_completed_over_expected_p100_against, avg_vertical_distance_against, passes_completed_over_expected_difference, avg_vertical_distance_difference **teams/goals-added:** team_id, minutes, data **teams/salaries:** team_id, count_players, total_guaranteed_compensation, avg_guaranteed_compensation, median_guaranteed_compensation, std_dev_guaranteed_compensation **games/xgoals:** game_id, date_time_utc, home_team_id, home_goals, home_team_xgoals, home_player_xgoals, away_team_id, away_goals, away_team_xgoals, away_player_xgoals, goal_difference, team_xgoal_difference, player_xgoal_difference, final_score_difference, home_xpoints, away_xpoints ``` -------------------------------- ### GET {base_url}{league}/games Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/endpoints.md Retrieves game data for a specified league. Supports filtering by game ID, team, season, stage, and status. Returns detailed game information including scores, teams, referees, and attendance. ```APIDOC ## GET {base_url}{league}/games ### Description Retrieves game data for a specified league. Supports filtering by game ID, team, season, stage, and status. Returns detailed game information including scores, teams, referees, and attendance. ### Method GET ### Endpoint {base_url}{league}/games ### Parameters #### Query Parameters - **game_id** (str or comma-joined list) - Optional - Game identifier(s) - **team_id** (str or comma-joined list) - Optional - Team identifier(s); team_names resolved client-side to IDs by substring match - **season_name** (str or list) - Optional - Season label(s); int years normalized to strings; years before 2013 rejected - **stage_name** (str or list) - Optional - Stage name(s) - **status** (str or list) - Optional - Game status; keywords: Abandoned, FullTime, PreMatch ### Response #### Success Response (200) - **game_id** (string) - Game identifier - **date_time_utc** (string) - Kickoff time, UTC - **home_score** / **away_score** (number) - Final score - **home_team_id** / **away_team_id** (string) - Team identifiers - **referee_id** (string) - Referee identifier - **stadium_id** (string) - Stadium identifier - **home_manager_id** / **away_manager_id** (string) - Manager identifiers - **expanded_minutes** (number) - Stoppage-adjusted minutes - **season_name** (string) - Season label - **matchday** (number) - Matchday number - **attendance** (number) - Attendance - **knockout_game** (boolean) - Playoff indicator - **last_updated_utc** (string) - Last update timestamp #### Response Example { "game_id": "string", "date_time_utc": "string", "home_score": 0, "away_score": 0, "home_team_id": "string", "away_team_id": "string", "referee_id": "string", "stadium_id": "string", "home_manager_id": "string", "away_manager_id": "string", "expanded_minutes": 0, "season_name": "string", "matchday": 0, "attendance": 0, "knockout_game": false, "last_updated_utc": "string" } ``` -------------------------------- ### Build the package Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Validate that the source distribution and wheel can be built. ```sh uv build ``` -------------------------------- ### Create and checkout a branch Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Navigate to the project directory and create a new branch for your changes. ```sh cd itscalledsoccer git branch BRANCH_NAME git checkout BRANCH_NAME ``` -------------------------------- ### AmericanSoccerAnalysis() - Client Initialization Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Initialize the AmericanSoccerAnalysis client. No authentication is required. ```APIDOC ## AmericanSoccerAnalysis() ### Description Initializes the client for accessing American Soccer Analysis data. No authentication is required. ### Method Constructor ### Endpoint `AmericanSoccerAnalysis()` ### Parameters None ### Request Example ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() ``` ``` -------------------------------- ### Create AmericanSoccerAnalysis client Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/docs/index.md Import the AmericanSoccerAnalysis class and instantiate a client to access the American Soccer Analysis API. ```python from itscalledsoccer.client import AmericanSoccerAnalysis asa_client = AmericanSoccerAnalysis() ``` -------------------------------- ### AmericanSoccerAnalysis.__init__ Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md Constructor for the AmericanSoccerAnalysis client. Initializes an HTTP session with retry and caching, sets up logging, and optionally preloads entity data. ```APIDOC ## AmericanSoccerAnalysis.__init__ ### Description Initializes an AmericanSoccerAnalysis client instance. Sets up an HTTP session with retry and caching, configures logging, and optionally preloads entity data. ### Method Constructor ### Signature ```python def __init__( self, proxies: dict | None = None, logging_level: str | None = "WARNING", lazy_load: bool | None = True, request_timeout: int = 30, ) -> None: ``` ### Parameters - **proxies** (dict | None) - Optional - Proxy mappings passed to the underlying requests session (session.proxies.update(proxies)). See the requests proxy docs. - **logging_level** (str | None) - Optional - Logging level for the instance-specific logger. Accepts "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL" (case-insensitive). Unrecognized values are ignored and an INFO message is logged. None leaves the logger at the root level. - **lazy_load** (bool | None) - Optional - When True, entity data is loaded on first use by each get_* entity method. When False, all five entity tables (players, teams, stadia, managers, referees) are fetched immediately during initialization. - **request_timeout** (int) - Optional - Timeout in seconds passed to every session.get(...) call. ### Configuration Behaviors - An HTTP session with a urllib3.util.retry.Retry strategy: total=3, backoff_factor=0.5 (retry delays 0.5s, 1s, 2s), status_forcelist=[429, 500, 502, 503, 504], allowed_methods=["GET"], mounted through requests.adapters.HTTPAdapter on both https:// and http://. - The retry session is wrapped in CacheControl(session, heuristic=ExpiresAfter(days=1)), so identical GET requests are served from an HTTP cache for up to one day. - An instance-specific logger created via getLogger(f"{__name__}.{id(self)}"), so each instance has an isolated logger name. ### Returns None ### Throws None raised by the constructor itself. With lazy_load=False it performs network requests through _get_entity, so requests-level errors (e.g., requests.exceptions.Timeout, requests.exceptions.ConnectionError) and HTTPError from raise_for_status() can propagate. ### Example - default client ```python from itscalledsoccer import AmericanSoccerAnalysis asa = AmericanSoccerAnalysis() # lazy loading, WARNING logging, 30s timeout xg = asa.get_player_xgoals(leagues="uslc", season_name="2023") ``` ### Example - eager loading with proxies and custom timeout ```python asa = AmericanSoccerAnalysis( proxies={"http": "http://proxy.local:8080", "https": "https://proxy.local:8080"}, logging_level="DEBUG", lazy_load=False, # fetch all entity tables at startup request_timeout=60, ) print(asa.players.shape) # already populated ``` ``` -------------------------------- ### Lint and format code Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Use ruff to check and format the project code. ```sh uv run ruff check itscalledsoccer uv run ruff format itscalledsoccer ``` -------------------------------- ### Clone the repository Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Commands to clone the repository using either SSH or HTTPS. ```sh # SSH git clone git@github.com:American-Soccer-Analysis/itscalledsoccer.git # HTTPS git clone https://github.com/American-Soccer-Analysis/itscalledsoccer.git ``` -------------------------------- ### AmericanSoccerAnalysis client configuration Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/types.md The main client class defining API versioning, base URL, supported leagues, and pagination limits. ```python class AmericanSoccerAnalysis: API_VERSION = "v1" BASE_URL = f"https://app.americansocceranalysis.com/api/{API_VERSION}/" LEAGUES = list(VALID_LEAGUES) MAX_API_LIMIT = 1000 ``` -------------------------------- ### Run tests Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Execute the test suite using pytest. ```sh uv run pytest ``` -------------------------------- ### Generate test coverage report Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Run tests and generate terminal and HTML coverage reports. ```sh uv run pytest --cov=itscalledsoccer --cov-report=term-missing --cov-report=html ``` -------------------------------- ### _execute_query(url, params) method Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md Executes a query by joining list-valued parameters into comma-separated strings and performing pagination. It returns a single polars DataFrame or a plain dictionary response. ```python def _execute_query( self, url: str, params: dict[str, str | list[str] | None] ) -> pl.DataFrame: ``` -------------------------------- ### Retrieve Player Goals Added (g+) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Fetch Goals Added data for players. ```python gplus = asa.get_player_goals_added( leagues="uslc", above_replacement=True ) ``` -------------------------------- ### Retrieve Player Expected Goals (xG) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Fetch Expected Goals data for players with optional filters like minimum minutes. ```python xg = asa.get_player_xgoals( leagues="uslc", season_name="2025", minimum_minutes=900 ) ``` -------------------------------- ### get_player_xgoals(leagues, season_name, minimum_minutes, minimum_shots, minimum_key_passes, shot_pattern, split_by_teams, split_by_seasons, split_by_games, general_position) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve player Expected Goals (xG) data with various filtering options. ```APIDOC ## get_player_xgoals(leagues, season_name, minimum_minutes, minimum_shots, minimum_key_passes, shot_pattern, split_by_teams, split_by_seasons, split_by_games, general_position) ### Description Retrieves player Expected Goals (xG) data, which measures the quality of shot chances a player creates or faces. ### Method `get_player_xgoals` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., "uslc" - **season_name** (string) - Optional - Season identifier, e.g., "2023" - **minimum_minutes** (number) - Optional - Minimum minutes played filter - **minimum_shots** (number) - Optional - Minimum shots filter - **minimum_key_passes** (number) - Optional - Minimum key passes filter - **shot_pattern** (string) - Optional - Shot pattern filter - **split_by_teams** (boolean) - Optional - Split results by team - **split_by_seasons** (boolean) - Optional - Split results by season - **split_by_games** (boolean) - Optional - Split results by game - **general_position** (string) - Optional - General position filter ### Request Example ```python xg = asa.get_player_xgoals( leagues="uslc", season_name="2025", minimum_minutes=900 ) ``` ``` -------------------------------- ### get_player_xgoals method signature Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md The method signature for retrieving player expected goals data from the AmericanSoccerAnalysis client. ```python def get_player_xgoals( self, leagues: str | list[str] = LEAGUES, **kwargs ) -> pl.DataFrame: ``` -------------------------------- ### Run static type checking Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/CONTRIBUTING.md Use mypy to perform static type checking on the project. ```sh uv run mypy itscalledsoccer ``` -------------------------------- ### get_team_xgoals(leagues, split_by_seasons, home_only, away_only, home_adjusted, even_game_state, zone, gamestate_trunc) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve team Expected Goals (xG) data with various filtering options. ```APIDOC ## get_team_xgoals(leagues, split_by_seasons, home_only, away_only, home_adjusted, even_game_state, zone, gamestate_trunc) ### Description Retrieves team Expected Goals (xG) data. ### Method `get_team_xgoals` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., "uslc" - **split_by_seasons** (boolean) - Optional - Split results by season - **home_only** (boolean) - Optional - Filter for home games only - **away_only** (boolean) - Optional - Filter for away games only - **home_adjusted** (boolean) - Optional - Apply home adjustment - **even_game_state** (boolean) - Optional - Filter for even game state - **zone** (number) - Optional - Zone filter (1-30) - **gamestate_trunc** (number) - Optional - Game state truncation filter (-2 to 2) ### Request Example ```python team_xg = asa.get_team_xgoals( leagues="uslc", split_by_seasons=True ) ``` ``` -------------------------------- ### get_team_salaries method signature Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md The method signature for retrieving team salary statistics. ```python def get_team_salaries( self, leagues: str | list[str] = "mls", **kwargs ) -> pl.DataFrame: ``` -------------------------------- ### get_player_xgoals error handling Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Demonstrates catching a ConflictingParametersError when both player IDs and player names are provided simultaneously. ```python from itscalledsoccer import AmericanSoccerAnalysis, ConflictingParametersError asa = AmericanSoccerAnalysis() try: asa.get_player_xgoals(player_ids=["p1"], player_names="Vela") except ConflictingParametersError as e: print(e) # "Please specify only player IDs or names, not both." ``` -------------------------------- ### Retrieve Game Data Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Fetch game schedules and results filtered by league, season, or team. ```python # Get games for a specific league and season uslc_2024_games = asa.get_games(leagues="uslc", seasons="2024") # Filter by team lou_games = asa.get_games(leagues="uslc", team_names="Louisville City") ``` -------------------------------- ### Player Statistics Methods - Common Arguments Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Common keyword-argument behavior across all player stat methods on AmericanSoccerAnalysis. These arguments are used by all six player-level statistics methods. ```APIDOC ## Player Statistics Methods - Common Arguments ### Description Common keyword arguments accepted by all player-level statistics methods on AmericanSoccerAnalysis. These methods return a polars.DataFrame. ### Parameters #### Keyword Arguments - **player_ids** (str | list[str]) - Optional - Mutually exclusive with player_names; names are resolved to ids first (substring matching). Sent to the API as player_id. - **player_names** (str | list[str]) - Optional - Mutually exclusive with player_ids; names are resolved to ids first (substring matching). Sent to the API as player_id. - **team_ids** (str | list[str]) - Optional - Mutually exclusive with team_names; names resolved to ids. Sent as team_id. - **team_names** (str | list[str]) - Optional - Mutually exclusive with team_ids; names resolved to ids. Sent as team_id. - **season_name** (str | list[str]) - Optional - Cannot be combined with a date range; validated/normalized by _check_season_name. - **start_date** (str) - Optional - YYYY-MM-DD format; cannot be combined with season_name. - **end_date** (str) - Optional - YYYY-MM-DD format; cannot be combined with season_name. - **minimum_minutes** (int) - Optional - Minimum threshold for sum of minutes played. - **split_by_teams** (bool) - Optional - Grouping indicator. - **split_by_seasons** (bool) - Optional - Grouping indicator. - **split_by_games** (bool) - Optional - Grouping indicator. ### Errors - InvalidLeagueError - InvalidParameterFormatError - ConflictingParametersError (IDs + names) - InvalidSeasonError (year before 2013) - SalaryDataError for salary methods with non-MLS leagues - requests.HTTPError/timeouts propagate from the session ``` -------------------------------- ### _get_stats(leagues, stat_type, entity, **kwargs) method Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md The shared engine for statistics methods. It normalizes parameters, validates leagues, resolves names to IDs, and concatenates results for multiple leagues. ```python def _get_stats( self, leagues: str | list[str], stat_type: str, entity: str, **kwargs ) -> pl.DataFrame: ``` -------------------------------- ### AmericanSoccerAnalysis Constructor Definition Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md The constructor signature for the AmericanSoccerAnalysis client, defining parameters for network and logging configuration. ```python def __init__( self, proxies: dict | None = None, logging_level: str | None = "WARNING", lazy_load: bool | None = True, request_timeout: int = 30, ) -> None: ``` -------------------------------- ### get_games(leagues, seasons, team_names) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve game data with optional filtering by league, season, and team. ```APIDOC ## get_games(leagues, seasons, team_names) ### Description Retrieves game data for the specified leagues, seasons, and teams. ### Method `get_games` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., "uslc" - **seasons** (string or list) - Optional - Season identifier(s), e.g., "2024" - **team_names** (string or list) - Optional - Team name(s), e.g., "Louisville City" ### Request Example ```python uslc_2024_games = asa.get_games(leagues="uslc", seasons="2024") lou_games = asa.get_games(leagues="uslc", team_names="Louisville City") ``` ``` -------------------------------- ### Retrieve Player Expected Pass (xPass) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Fetch Expected Pass data for players. ```python xpass = asa.get_player_xpass( leagues="uslc", minimum_minutes=900 ) ``` -------------------------------- ### get_player_goals_added(leagues, above_replacement) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve player Goals Added (g+) data. ```APIDOC ## get_player_goals_added(leagues, above_replacement) ### Description Retrieves player Goals Added (g+) data, which measures total value contribution across all actions. ### Method `get_player_goals_added` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., "uslc" - **above_replacement** (boolean) - Optional - Filter for above replacement value ### Request Example ```python gplus = asa.get_player_goals_added( leagues="uslc", above_replacement=True ) ``` ``` -------------------------------- ### get_stadia() Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve stadium data. ```APIDOC ## get_stadia() ### Description Retrieves stadium data. ### Method `get_stadia` ### Parameters None ### Request Example ```python stadia = asa.get_stadia() ``` ``` -------------------------------- ### Exception Hierarchy Tree Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/errors.md Visual representation of the ASAError exception hierarchy. ```text Exception └── ASAError ├── InvalidEntityTypeError ├── InvalidLeagueError ├── SalaryDataError ├── ConflictingParametersError ├── InvalidParameterFormatError └── InvalidSeasonError ``` -------------------------------- ### get_team_xpass(leagues, split_by_seasons, home_only, away_only, home_adjusted, even_game_state, zone, gamestate_trunc) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve team Expected Pass (xPass) data with various filtering options. ```APIDOC ## get_team_xpass(leagues, split_by_seasons, home_only, away_only, home_adjusted, even_game_state, zone, gamestate_trunc) ### Description Retrieves team Expected Pass (xPass) data. ### Method `get_team_xpass` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., ["uslc", "nwsl"] - **split_by_seasons** (boolean) - Optional - Split results by season - **home_only** (boolean) - Optional - Filter for home games only - **away_only** (boolean) - Optional - Filter for away games only - **home_adjusted** (boolean) - Optional - Apply home adjustment - **even_game_state** (boolean) - Optional - Filter for even game state - **zone** (number) - Optional - Zone filter (1-30) - **gamestate_trunc** (number) - Optional - Game state truncation filter (-2 to 2) ### Request Example ```python team_xpass = asa.get_team_xpass( leagues=["uslc", "nwsl"], split_by_seasons=True ) ``` ``` -------------------------------- ### Re-exported symbols in itscalledsoccer/__init__.py Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/american-soccer-analysis.md This snippet shows the package-level exports for the AmericanSoccerAnalysis client and associated error classes. ```python from itscalledsoccer.client import AmericanSoccerAnalysis from itscalledsoccer.errors import ( ASAError, ConflictingParametersError, InvalidEntityTypeError, InvalidLeagueError, InvalidParameterFormatError, InvalidSeasonError, SalaryDataError, ) __all__ = [ "AmericanSoccerAnalysis", "ASAError", "ConflictingParametersError", "InvalidEntityTypeError", "InvalidLeagueError", "InvalidParameterFormatError", "InvalidSeasonError", "SalaryDataError", ] ``` -------------------------------- ### get_players(names) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Search for players by case-insensitive substring. Returns the first matching entity. ```APIDOC ## get_players(names) ### Description Search for players by case-insensitive substring. Returns the first matching entity. ### Method GET ### Endpoint asa.get_players ### Parameters #### Query Parameters - **names** (string) - Required - Case-insensitive substring to match player names. ### Request Example ```python asa.get_players(names="Carlos Vela") ``` ### Response #### Success Response (200) - **player** (object) - The first matching player entity. #### Response Example ```json { "player": {} } ``` ``` -------------------------------- ### get_player_xpass(leagues, minimum_minutes) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Retrieve player Expected Pass (xPass) data. ```APIDOC ## get_player_xpass(leagues, minimum_minutes) ### Description Retrieves player Expected Pass (xPass) data, which measures pass difficulty and creative play value. ### Method `get_player_xpass` ### Parameters - **leagues** (string or list) - Required - League identifier(s), e.g., "uslc" - **minimum_minutes** (number) - Optional - Minimum minutes played filter ### Request Example ```python xpass = asa.get_player_xpass( leagues="uslc", minimum_minutes=900 ) ``` ``` -------------------------------- ### get_team_goals_added method signature Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/team-stats-methods.md The method signature for retrieving team goals added statistics. ```python def get_team_goals_added( self, leagues: str | list[str] = LEAGUES, **kwargs ) -> pl.DataFrame: ``` -------------------------------- ### get_goalkeeper_xgoals definition Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md The method signature for retrieving goalkeeper expected goals statistics. ```python def get_goalkeeper_xgoals( self, leagues: str | list[str] = LEAGUES, **kwargs ) -> pl.DataFrame: ``` -------------------------------- ### get_player_salaries error handling Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/player-stats-methods.md Demonstrates catching a SalaryDataError when attempting to request salary data for a non-MLS league. ```python from itscalledsoccer import AmericanSoccerAnalysis, SalaryDataError asa = AmericanSoccerAnalysis() try: asa.get_player_salaries(leagues="nwsl") except SalaryDataError as e: print(e) # "Only MLS salary data is publicly available." ``` -------------------------------- ### get_teams(names) Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/README.md Search for teams by case-insensitive substring. Returns the first matching entity. ```APIDOC ## get_teams(names) ### Description Search for teams by case-insensitive substring. Returns the first matching entity. ### Method GET ### Endpoint asa.get_teams ### Parameters #### Query Parameters - **names** (string) - Required - Case-insensitive substring to match team names. ### Request Example ```python asa.get_teams(names="LA") ``` ### Response #### Success Response (200) - **team** (object) - The first matching team entity. #### Response Example ```json { "team": {} } ``` ``` -------------------------------- ### get_players method signature Source: https://github.com/american-soccer-analysis/itscalledsoccer/blob/main/_autodocs/api-reference/entity-methods.md The definition of the get_players method, which accepts optional filters for leagues, IDs, and names. ```python def get_players( self, leagues: str | list[str] | None = None, ids: str | list[str] | None = None, names: str | list[str] | None = None, ) -> pl.DataFrame: ```