itscalledsoccer

Table of Contents

• Background
• Features
• Installation
  • Stable Release
  • Development Version
• Quick Start
• Usage Examples
  • Entities
  • Games
  • Player Statistics
    • Expected Goals (xG)
    • Expected Pass (xPass)
    • Goals Added (g+)
  • Team Statistics
• Advanced Usage
  • Substring Name Matching
• API Reference
• Other Versions
• Contributing
• License

Background

itscalledsoccer is a Python wrapper around the American Soccer Analysis API, providing programmatic access to advanced soccer analytics across North American leagues.

What you can measure:

• Expected Goals (xG) — Shot quality and finishing efficiency
• Expected Passes (xPass) — Pass difficulty and creative play
• Goals Added (g+) — Total value contribution of players
• Salaries — MLS salary and spend data

The API is free and public — no authentication required.

Supported leagues:

Useful links:

• Full API documentation: american-soccer-analysis.github.io/itscalledsoccer/reference
• Web app: app.americansocceranalysis.com
• Release notes: CHANGELOG.md
• Security policy: SECURITY.md

Features

• 15 API methods covering players, teams, games, and advanced statistics
• Substring name matching — search by partial names or abbreviations ("LA", "Vela")
• Type hints — full type annotations on all public methods
• Consistent interface — same patterns across all 7 leagues

Installation

Stable Release

pip install itscalledsoccer

Development Version

git clone https://github.com/American-Soccer-Analysis/itscalledsoccer.git
cd itscalledsoccer
pip install -e ".[dev]"

Requirements: Python 3.10+, requests, polars, cachecontrol

Quick Start

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"
)

For the complete method reference, see Usage Examples below.

Usage Examples

Entities

Retrieve core soccer entities with optional filtering:

# Same interface for all entity types
uslc_players = asa.get_players(leagues="uslc")
teams = asa.get_teams(leagues=["uslc", "nwsl"])
stadia = asa.get_stadia()
managers = asa.get_managers(leagues="uslc")
referees = asa.get_referees(leagues=["uslc", "mls"])

Available entities: players, teams, stadia, managers, referees

Games

# 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

Expected Goals (xG)

Expected Goals measures the quality of shot chances a player creates or faces.

xg = asa.get_player_xgoals(
    leagues="uslc",
    season_name="2025",
    minimum_minutes=900
)

Available filters: minimum_minutes, minimum_shots, minimum_key_passes, shot_pattern, split_by_teams, split_by_seasons, split_by_games, general_position

Expected Pass (xPass)

Expected Pass measures pass difficulty and creative play value.

xpass = asa.get_player_xpass(
    leagues="uslc",
    minimum_minutes=900
)

Goals Added (g+)

Goals Added measures total value contribution across all actions.

gplus = asa.get_player_goals_added(
    leagues="uslc",
    above_replacement=True
)

Note: Goalkeeper statistics use the same interface — get_goalkeeper_xgoals() and get_goalkeeper_goals_added().

Team Statistics

# Team Expected Goals
team_xg = asa.get_team_xgoals(
    leagues="uslc",
    split_by_seasons=True
)

# Team Expected Pass
team_xpass = asa.get_team_xpass(
    leagues=["uslc", "nwsl"],
    split_by_seasons=True
)

# Team Salaries (MLS only)
team_salaries = asa.get_team_salaries(
    leagues="mls",
    split_by_teams=True
)

Team-specific filters: home_only, away_only, home_adjusted, even_game_state, zone (1-30), gamestate_trunc (-2 to 2)

Advanced Usage

Substring Name Matching

Search by case-insensitive substrings. Returns the first matching entity:

# Player names
asa.get_players(names="Carlos Vela")

# Team names
asa.get_teams(names="LA")

API Reference

Complete documentation: american-soccer-analysis.github.io/itscalledsoccer/reference

The reference includes:

• All 15 methods and their parameters
• Complete field descriptions for each endpoint
• Type signatures and defaults

Common questions:

• No API key needed? Correct — the API is public and free.
• Why is my query slow? Large queries may take a moment. Subsequent identical queries are cached.
• What do the metrics mean?
  • xG: Shot quality (0-1 per shot)
  • xPass: Pass completion probability (0-1)
  • g+: Measures a player's total on-ball contribution in attack and defense

For detailed methodology, see American Soccer Analysis.

Other Versions

• R: itscalledsoccer-r
• JavaScript: itscalledsoccer-js

Contributing

See CONTRIBUTING.md for code of conduct, development setup, pull request process, and issue reporting.

License

MIT © itscalledsoccer authors