Statsbombpy

https://github.com/statsbomb/statsbombpy
Admin
Statsbombpy is a Python package that allows users to easily stream StatsBomb data into Python using...
Tokens:50,321
Snippets:512
Trust Score:8.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install HTTP Caching with requests_cache

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

This code installs an HTTP cache using the `requests_cache` library. It configures a SQLite backend stored in the system's temporary directory, with cache entries expiring after 600 seconds.

```python
from requests_cache import install_cache
from tempfile import mkdtemp

install_cache(mkdtemp(), backend="sqlite", expire_after=600)
```

--------------------------------

### Get Match Lineup

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve the starting lineups for a given match ID. Lineups can be accessed by team name.

```python
from statsbombpy import sb

lineups = sb.lineups(match_id=303299)

# Access by team name
schalke = lineups["Schalke 04"]
print(schalke[["player_name", "jersey_number", "position"]].head())
```

--------------------------------

### Install StatsBombPy

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Install the StatsBombPy library using pip.

```bash
pip install statsbombpy
```

--------------------------------

### Set Environment Variables for Credentials

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Example of setting environment variables for API username and password.

```bash
export SB_USERNAME="your_username"
export SB_PASSWORD="your_password"
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Demonstrates setting environment variables and using library functions with both default and custom credentials.

```python
import os
from statsbombpy import sb

# Set environment variables
os.environ["SB_USERNAME"] = "myusername"
os.environ["SB_PASSWORD"] = "mypassword"
os.environ["SB_CORES"] = "8"

# Now all functions use these credentials and concurrency settings
competitions = sb.competitions()
matches = sb.matches(competition_id=9, season_id=42)

# Or explicitly pass credentials to override env vars
custom_creds = {"user": "other_user", "passwd": "other_pass"}
events = sb.events(match_id=303299, creds=custom_creds)

# Concurrency is applied automatically to these functions
all_events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020"
    # Uses SB_CORES workers
)

```

--------------------------------

### Setup for Free Open Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Access free open data from StatsBomb without needing API credentials. This is suitable for public datasets.

```python
from statsbombpy import sb

# No credentials needed - uses free open data
competitions = sb.competitions()
```

--------------------------------

### Setup with Inline Credentials

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Provide your StatsBomb API credentials directly within your Python script. This method is an alternative to environment variables.

```python
from statsbombpy import sb

creds = {"user": "your_username", "passwd": "your_password"}
competitions = sb.competitions(creds=creds)
```

--------------------------------

### Get Match Lineups

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieves the lineup for a specific team in a given match. The result is a dictionary where keys are team names.

```python
sb.lineups(match_id=303299)["Eintracht Frankfurt"]
```

--------------------------------

### Get Match Lineups

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-lineups.md

Fetches lineup information for both teams in a match. Supports returning data as pandas DataFrames or raw dictionaries.

```APIDOC
## GET /lineups

### Description
Returns lineup information for both teams in a match, including player details and team metadata.

### Method
GET

### Endpoint
`/lineups`

### Parameters
#### Query Parameters
- **match_id** (int) - Required - Numeric match ID (e.g., 303299).
- **fmt** (str) - Optional - Output format. Accepts "dataframe" or "dict". Defaults to "dataframe".
- **creds** (dict) - Optional - Authentication credentials with keys "user" and "passwd". Defaults to `DEFAULT_CREDS`.

### Request Example
```python
from statsbombpy import sb

# Get lineups for a specific match in dataframe format
lineups_df = sb.lineups(match_id=303299)

# Get lineups in raw dictionary format
lineups_dict = sb.lineups(match_id=303299, fmt="dict")
```

### Response
#### Success Response (200)
- **DataFrame mode** (`fmt="dataframe"`): Dictionary with team names as keys, each value is a pandas DataFrame with columns: player_id, player_name, player_nickname, birth_date, player_gender, player_height, player_weight, jersey_number, country.
- **Dict mode** (`fmt="dict"`): Raw dictionary structure from API including additional metadata like formations and events if available.

#### Response Example (DataFrame Mode)
{
  "Eintracht Frankfurt": [
    {
      "player_id": 12345,
      "player_name": "Filip Kostic",
      "player_nickname": "Kostic",
      "birth_date": "1992-11-01",
      "player_gender": "male",
      "player_height": "184 cm",
      "player_weight": "75 kg",
      "jersey_number": 10,
      "country": "Serbia"
    }
    // ... more players
  ],
  "Bayer Leverkusen": [
    {
      "player_id": 67890,
      "player_name": "Moussa Diaby",
      "player_nickname": "Diaby",
      "birth_date": "1999-11-07",
      "player_gender": "male",
      "player_height": "170 cm",
      "player_weight": "65 kg",
      "jersey_number": 19,
      "country": "France"
    }
    // ... more players
  ]
}

#### Response Example (Dict Mode)
{
  "3204": {
    "team_name": "Eintracht Frankfurt",
    "formations": [
      {
        "period": "1H",
        "formation": "3-4-2-1"
      }
    ],
    "players": [
      {
        "player_id": 12345,
        "player_name": "Filip Kostic",
        "player_nickname": "Kostic",
        "birth_date": "1992-11-01",
        "player_gender": "male",
        "player_height": "184 cm",
        "player_weight": "75 kg",
        "jersey_number": 10,
        "country": {"name": "Serbia"},
        "position": {"name": "Left Wing", "id": 11}
      }
      // ... more players
    ]
  },
  "3205": {
    "team_name": "Bayer Leverkusen",
    "players": [
      {
        "player_id": 67890,
        "player_name": "Moussa Diaby",
        "player_nickname": "Diaby",
        "birth_date": "1999-11-07",
        "player_gender": "male",
        "player_height": "170 cm",
        "player_weight": "65 kg",
        "jersey_number": 19,
        "country": {"name": "France"},
        "position": {"name": "Right Wing", "id": 13}
      }
      // ... more players
    ]
  }
}

### Exceptions
- **HTTP errors**: Propagated if match_id is invalid.
```

--------------------------------

### Get Matches for a Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Fetch all matches for a specific competition and season using their IDs. Ensure you have the correct competition and season IDs.

```python
from statsbombpy import sb

# First, find the competition and season IDs
matches = sb.matches(competition_id=9, season_id=42)
print(matches[["home_team", "away_team", "home_score", "away_score"]].head())
```

--------------------------------

### Access Competitions Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieve a list of available competitions. Use fmt='dict' to get the data as a Python dictionary.

```python
sb.competitions(fmt="dict")
```

--------------------------------

### Get All Match Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Fetch all events for a specific match ID. This provides a comprehensive list of actions that occurred during the game.

```python
from statsbombpy import sb

# Single match, all events
events = sb.events(match_id=303299)
print(f"Total events: {len(events)}")
print(events[["player", "type", "location"]].head())
```

--------------------------------

### Get All Events from a Match

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieve all events for a specific match ID and display the total count and a preview of key columns.

```python
from statsbombpy import sb

events = sb.events(match_id=303299)
print(f"Total events: {len(events)}")
print(events[["player", "type", "pass_outcome"]].head())
```

--------------------------------

### Get Competition 360 Frames

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieves 360 tracking data for an entire competition season.

```APIDOC
## Get Competition 360 Frames

### Description
Fetches 360-degree tracking data for all matches within a specified competition, division, and season.

### Method
`sb.competition_frames(country, division, season, creds)`

### Parameters
#### Query Parameters
- **country** (str) - Required - The name of the country the competition is in (e.g., 'Europe').
- **division** (str) - Required - The name of the division (e.g., 'Champions League').
- **season** (str) - Required - The season identifier (e.g., '2022/2023').
- **creds** (dict) - Required - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`).

### Request Example
```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}
comp_frames = sb.competition_frames(
    country="Europe",
    division="Champions League",
    season="2022/2023",
    creds=creds
)
```

### Response
#### Success Response
Returns a pandas DataFrame containing 360 tracking data for the specified competition season.
```

--------------------------------

### API Client: Get Matches

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-entities.md

Retrieves a list of matches for a specific competition and season using authenticated API access. It constructs the URL, fetches the data, and transforms it.

```python
def matches(competition_id: int, season_id: int, creds: dict) -> dict:
    url = f"{HOSTNAME}/api/{VERSIONS['matches']}/competitions/{competition_id}/seasons/{season_id}/matches"
    matches_list = get_resource(url, creds)
    return ents.matches(matches_list)  # Transform here
```

--------------------------------

### Get Matches as Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-matches.md

Fetches match data for a specified competition and season, returning it as a raw dictionary. This allows direct access to nested team information.

```python
# Get raw match dictionary
matches_dict = sb.matches(competition_id=9, season_id=42, fmt="dict")
first_match = matches_dict[303299]
print(first_match["home_team"]["name"])
```

--------------------------------

### Get Lineups as DataFrames

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-lineups.md

Retrieves lineup information for a specific match and returns it as pandas DataFrames. Access individual team lineups using team names as keys.

```python
from statsbombpy import sb

# Get lineups for a specific match
lineups = sb.lineups(match_id=303299)

# Access a specific team's lineup
frankfurt_lineup = lineups["Eintracht Frankfurt"]
print(frankfurt_lineup[["player_name", "jersey_number", "position"]])

# Get player details
first_player = frankfurt_lineup.iloc[0]
print(f"{first_player['player_name']} ({first_player['country']})")
```

--------------------------------

### Public Module: Get Competitions

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-entities.md

Retrieves a list of competitions from the open data source. This function uses get_response with a predefined path and applies the same transformation as the API client.

```python
def competitions():
    competitions_list = get_response(OPEN_DATA_PATHS["competitions"])
    return ents.competitions(competitions_list)  # Same transformation
```

--------------------------------

### Get Match Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Fetches all events for a specific match. Optionally, can include 360 tracking metrics.

```APIDOC
## Get Match Events

### Description
Retrieves all events associated with a given match ID. This function can also merge in 360 tracking data if requested.

### Method
`sb.events(match_id, include_360_metrics=False, creds=None)`

### Parameters
#### Path Parameters
- **match_id** (int) - Required - The unique identifier for the match.

#### Query Parameters
- **include_360_metrics** (bool) - Optional - If True, merges 360 tracking data into the events.
- **creds** (dict) - Optional - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`). If not provided, uses environment variables or no authentication for open data.

### Request Example
```python
from statsbombpy import sb

# Get basic events
events_basic = sb.events(match_id=303299)

# Get events with 360 metrics
creds = {"user": "username", "passwd": "password"}
events_360 = sb.events(match_id=3837323, include_360_metrics=True, creds=creds)
```

### Response
#### Success Response
Returns a pandas DataFrame containing event data for the match. If `include_360_metrics` is True, additional columns from 360 tracking data will be present.
```

--------------------------------

### Get Events by Type

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve and categorize events from a match by their type, such as passes, shots, or dribbles. This allows for focused analysis of specific actions.

```python
from statsbombpy import sb

# Split events by type
events_split = sb.events(match_id=303299, split=True)

passes = events_split["passes"]
shots = events_split["shots"]
dribbles = events_split["dribbles"]

print(f"Passes: {len(passes)}")
print(f"Shots: {len(shots)}")
print(f"Dribbles: {len(dribbles)}")
```

--------------------------------

### Get Events Split by Type

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Fetch events for a match and split them into different types such as passes, shots, and dribbles.

```python
from statsbombpy import sb

events_split = sb.events(match_id=303299, split=True)
passes = events_split["passes"]
shots = events_split["shots"]
dribbles = events_split["dribbles"]
```

--------------------------------

### Get Season-Wide Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve all events for a specific competition, division, and season. This is useful for season-wide analysis.

```python
from statsbombpy import sb

# Get entire season
events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020"
)
```

--------------------------------

### Get 360 Frames as DataFrame

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-frames.md

Fetches 360 tracking data for a given match ID and returns it as a pandas DataFrame. Requires authentication credentials.

```python
from statsbombpy import sb

# Get 360 frames as DataFrame
frames = sb.frames(
    match_id=3837323,
    creds={"user": "username", "passwd": "password"}
)
print(frames.columns)
print(f"Total player observations: {len(frames)}")
```

--------------------------------

### API Client: Get Competitions

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-entities.md

Retrieves a list of competitions using authenticated API access. It calls the internal get_resource function and then transforms the data using entities.competitions.

```python
def competitions(creds: dict) -> dict:
    url = f"{HOSTNAME}/api/{VERSIONS['competitions']}/competitions"
    competitions_list = get_resource(url, creds)
    return ents.competitions(competitions_list)  # Transform here
```

--------------------------------

### Get Competition-Wide Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieve all events for a specific competition, division, and season, utilizing parallel processing for efficiency.

```python
from statsbombpy import sb

# Gets all events for Bundesliga 2019/2020 with parallel processing
all_events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020"
)
print(f"Total events in season: {len(all_events)}")
```

--------------------------------

### Get Competitions as Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competitions.md

Retrieves available competitions and seasons as a dictionary. This format allows for direct access to specific competition details using a tuple key.

```python
# Get competitions as dictionary
competitions_dict = sb.competitions(fmt="dict")
comp = competitions_dict["Germany", "1. Bundesliga", "2019/2020", "male"]
print(comp["competition_id"])
```

--------------------------------

### Get Player Season Stats (DataFrame)

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-player-season-stats.md

Fetches player season statistics as a pandas DataFrame. Requires competition and season IDs, and optionally credentials. Useful for general analysis and filtering.

```python
from statsbombpy import sb

# Get player season stats for Bundesliga 2019/2020
stats = sb.player_season_stats(
    competition_id=9,
    season_id=42,
    creds={"user": "username", "passwd": "password"}
)
print(f"Total players: {len(stats)}")
print(stats.columns)
```

--------------------------------

### Get Competitions

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieves a list of available competitions. Authentication can be handled via environment variables, explicit credentials, or omitted for open data.

```APIDOC
## Get Competitions

### Description
Retrieves a list of available competitions. This function can be called with or without explicit credentials, depending on the data's accessibility.

### Method
`sb.competitions()`

### Parameters
None directly, but relies on authentication methods (environment variables, explicit `creds` dictionary, or none for open data).

### Request Example
```python
from statsbombpy import sb

# Using environment variables (recommended)
competitions_env = sb.competitions()

# Using explicit credentials
creds = {"user": "your_username", "passwd": "your_password"}
competitions_creds = sb.competitions(creds=creds)

# For open data
competitions_open = sb.competitions()
```

### Response
#### Success Response
Returns a pandas DataFrame containing competition details.
```

--------------------------------

### Get All Events for a Competition Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competition-events.md

Retrieves all events for a given country, division, and season in DataFrame format. This is the default behavior when 'split' is False and 'fmt' is 'dataframe'.

```python
from statsbombpy import sb

# Get all events for a competition season (DataFrame mode)
events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020",
    gender="male"
)
print(f"Total events: {len(events)}")
```

--------------------------------

### Get All 360 Frames for a Competition Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competition-frames.md

Fetches all 360-degree tracking data for a given country, division, and season. Requires API authentication. Outputs a pandas DataFrame by default.

```python
from statsbombpy import sb

# Get all 360 frames for a competition season
frames = sb.competition_frames(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020",
    creds={"user": "username", "passwd": "password"}
)
print(f"Total player observations: {len(frames)}")
print(frames.columns)
```

--------------------------------

### Get Player Season Stats (JSON)

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-player-season-stats.md

Retrieves player season statistics in raw JSON format. Use this when you need the unprocessed data directly from the API.

```python
# Get raw JSON
stats_json = sb.player_season_stats(
    competition_id=9,
    season_id=42,
    fmt="json",
    creds=creds
)
```

--------------------------------

### Get Matches as DataFrame

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-matches.md

Retrieves all matches for a given competition and season in a pandas DataFrame format. Displays key match details like IDs, teams, and scores.

```python
from statsbombpy import sb

# Get all matches in Bundesliga 2019/2020
matches = sb.matches(competition_id=9, season_id=42)
print(matches[["match_id", "home_team", "away_team", "home_score", "away_score"]])
```

--------------------------------

### Get Player Match Stats as DataFrame

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-player-match-stats.md

Fetches player match statistics and returns them as a pandas DataFrame. Requires valid API credentials. Useful for analyzing player performance metrics like passes, tackles, and interceptions.

```python
from statsbombpy import sb

# Get player match stats
stats = sb.player_match_stats(
    match_id=303299,
    creds={"user": "username", "passwd": "password"}
)
print(stats.columns)
print(f"Total players: {len(stats)}")

# Get stats for specific team
home_team_stats = stats[stats["team"] == "Schalke 04"]
print(home_team_stats[["player", "passes", "tackles", "interceptions"]])

# Find top performers
top_passers = stats.nlargest(5, "passes")[["player", "passes", "passes_completed"]]
print(top_passers)
```

--------------------------------

### Import and Fetch Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-index.md

Recommended way to import the library and fetch match events using the 'sb' alias.

```python
from statsbombpy import sb
events = sb.events(match_id=303299)
```

--------------------------------

### Perform Authenticated GET Request

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

Makes an authenticated HTTP GET request to a StatsBomb API endpoint using basic authentication. The response is automatically cached for 10 minutes. Returns parsed JSON on success or an empty list on HTTP error.

```python
from statsbombpy.api_client import get_resource

url = "https://data.statsbombservices.com/api/v4/competitions"
creds = {"user": "myuser", "passwd": "mypass"}
result = get_resource(url, creds)
```

--------------------------------

### Get Player Match Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Accesses player statistics for a specific match.

```APIDOC
## Get Player Match Stats

### Description
Retrieves player statistics for a particular match, allowing analysis of individual performance within that game.

### Method
`sb.player_match_stats(match_id, creds)`

### Parameters
#### Path Parameters
- **match_id** (int) - Required - The unique identifier for the match.

#### Request Body
- **creds** (dict) - Required - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`).

### Request Example
```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}
match_stats = sb.player_match_stats(match_id=303299, creds=creds)
```

### Response
#### Success Response
Returns a pandas DataFrame with player statistics for the match.
```

--------------------------------

### Get Team Season Stats (DataFrame)

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-team-season-stats.md

Retrieves aggregated team statistics for a competition season in a pandas DataFrame. Requires valid competition and season IDs, along with authentication credentials.

```python
from statsbombpy import sb

# Get team season stats for Bundesliga 2019/2020
stats = sb.team_season_stats(
    competition_id=9,
    season_id=42,
    creds={"user": "username", "passwd": "password"}
)
print(f"Total teams: {len(stats)}")
print(stats.columns)
```

--------------------------------

### Get Competition Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieves all events for a specified competition, division, and season.

```APIDOC
## Get Competition Events

### Description
Fetches all events for a specific competition, division, and season. This is useful for analyzing an entire league or season.

### Method
`sb.competition_events(country, division, season, creds=None)`

### Parameters
#### Query Parameters
- **country** (str) - Required - The name of the country the competition is in (e.g., 'Germany').
- **division** (str) - Required - The name of the division (e.g., '1. Bundesliga').
- **season** (str) - Required - The season identifier (e.g., '2019/2020').
- **creds** (dict) - Optional - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`). If not provided, uses environment variables or no authentication for open data.

### Request Example
```python
from statsbombpy import sb

all_events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020"
)
```

### Response
#### Success Response
Returns a pandas DataFrame containing all events for the specified competition and season.
```

--------------------------------

### Get Player Season Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Accesses player statistics aggregated over an entire season.

```APIDOC
## Get Player Season Stats

### Description
Retrieves aggregated player statistics for a specific competition season, enabling season-long performance analysis.

### Method
`sb.player_season_stats(competition_id, season_id, creds)`

### Parameters
#### Query Parameters
- **competition_id** (int) - Required - The unique identifier for the competition.
- **season_id** (int) - Required - The unique identifier for the season.
- **creds** (dict) - Required - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`).

### Request Example
```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}
season_stats = sb.player_season_stats(
    competition_id=9,
    season_id=42,
    creds=creds
)
```

### Response
#### Success Response
Returns a pandas DataFrame with aggregated player statistics for the season.
```

--------------------------------

### Get Lineups as Raw Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-lineups.md

Fetches lineup information for a specific match in raw dictionary format, which may include additional metadata such as formations and events. Access team data using team IDs.

```python
from statsbombpy import sb

# Raw dict format includes metadata
lineups_raw = sb.lineups(match_id=303299, fmt="dict")
schalke = lineups_raw[3204]  # Team ID
print(schalke.get("formations"))  # May contain formation info
```

--------------------------------

### Get Player Match Statistics

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Fetch player statistics for a specific match, requiring API credentials. This includes metrics like passes, tackles, and interceptions, and allows for identifying top performers.

```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}

# Match-level stats
match_stats = sb.player_match_stats(match_id=303299, creds=creds)
print(match_stats[["player", "passes", "tackles", "interceptions"]].head())

# Top performers
print("\nTop 5 passers:")
print(match_stats.nlargest(5, "passes")[["player", "passes", "passes_completed"]])
```

--------------------------------

### Set Environment Variables for Authentication

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Set environment variables for username, password, and optional core count for authentication. This is the recommended method.

```bash
export SB_USERNAME="your_username"
export SB_PASSWORD="your_password"
export SB_CORES=8  # Optional: control parallelization
```

--------------------------------

### Get Match 360 Frames

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieves 360 tracking data (frames) for a specific match.

```APIDOC
## Get Match 360 Frames

### Description
Fetches detailed 360-degree tracking data for every moment within a specific match.

### Method
`sb.frames(match_id, creds)`

### Parameters
#### Path Parameters
- **match_id** (int) - Required - The unique identifier for the match.

#### Request Body
- **creds** (dict) - Required - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`).

### Request Example
```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}
frames = sb.frames(match_id=3837323, creds=creds)
```

### Response
#### Success Response
Returns a pandas DataFrame containing 360 tracking data for the match.
```

--------------------------------

### get_resource

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

Performs an authenticated HTTP GET request to a specified API URL using provided credentials. It handles response parsing and caching, returning the JSON response on success or an empty list on HTTP errors.

```APIDOC
## get_resource

### Description
Performs authenticated HTTP GET request to API. Uses HTTP Basic Authentication and automatically caches requests.

### Method
```python
def get_resource(url: str, creds: dict) -> Union[list, dict]
```

### Parameters
#### Path Parameters
- **url** (str) - Required - Full URL of API endpoint
- **creds** (dict) - Required - Credentials dict with "user" and "passwd" keys

### Return Value
- Parsed JSON response (list or dict) on success
- Empty list `[]` on HTTP error

### Behavior
- Uses HTTP Basic Authentication
- Makes GET request with provided credentials
- Returns parsed JSON on HTTP 200 status
- Prints error message and returns `[]` for non-200 status
- Automatically cached via requests_cache (10 minute TTL)

### Example
```python
from statsbombpy.api_client import get_resource

url = "https://data.statsbombservices.com/api/v4/competitions"
creds = {"user": "myuser", "passwd": "mypass"}
result = get_resource(url, creds)
```
```

--------------------------------

### Accessing Competitions with and without Credentials

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-public.md

Demonstrates how to fetch competition data. The first call automatically uses public data, while the second explicitly uses provided credentials to access the API.

```python
from statsbombpy import sb

# This automatically uses public.competitions()
competitions = sb.competitions()

# With credentials, uses api_client.competitions() instead
creds = {"user": "myuser", "passwd": "mypass"}
competitions_api = sb.competitions(creds=creds)
```

--------------------------------

### Load Credentials Automatically

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Python code demonstrating automatic loading of credentials from environment variables.

```python
from statsbombpy import sb
competitions = sb.competitions()  # Uses SB_USERNAME and SB_PASSWORD
```

--------------------------------

### Get Events by Type

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieves events for a match, split into different types such as passes, shots, and dribbles.

```APIDOC
## Get Events by Type

### Description
Fetches events for a given match and returns them categorized by event type (e.g., passes, shots, dribbles).

### Method
`sb.events(match_id, split=True, creds=None)`

### Parameters
#### Path Parameters
- **match_id** (int) - Required - The unique identifier for the match.

#### Query Parameters
- **split** (bool) - Required - Set to True to split events by type.
- **creds** (dict) - Optional - A dictionary containing user credentials (`{"user": "username", "passwd": "password"}`). If not provided, uses environment variables or no authentication for open data.

### Request Example
```python
from statsbombpy import sb

events_split = sb.events(match_id=303299, split=True)
passes = events_split["passes"]
shots = events_split["shots"]
dribbles = events_split["dribbles"]
```

### Response
#### Success Response
Returns a dictionary where keys are event types (e.g., 'passes', 'shots') and values are pandas DataFrames containing the respective events.
```

--------------------------------

### Authenticate using Environment Variables

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Automatically uses environment variables (SB_USERNAME, SB_PASSWORD) for authentication when fetching competitions data.

```python
from statsbombpy import sb

# Uses SB_USERNAME and SB_PASSWORD automatically
competitions = sb.competitions()
```

--------------------------------

### Alternative Advanced Imports

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-index.md

Alternative import paths for advanced users, including API client, public, helpers, and configuration settings.

```python
from statsbombpy import api_client, public, helpers
from statsbombpy.config import DEFAULT_CREDS, MAX_CONCURRENCY
```

--------------------------------

### Catching NoAuthWarning

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/errors.md

Demonstrates how to catch the NoAuthWarning when no user credentials are provided, indicating open data access only. This is useful for handling scenarios where authentication is optional.

```python
import warnings
from statsbombpy.api_client import NoAuthWarning

warnings.filterwarnings('error', category=NoAuthWarning)
try:
    from statsbombpy import sb
    competitions = sb.competitions(creds={"user": "", "passwd": ""})
except NoAuthWarning as w:
    print(f"No auth warning: {w}")
```

--------------------------------

### Check Authentication Credentials

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

Verifies if valid user and password credentials are provided. Returns False and raises a warning if credentials are missing or empty.

```python
from statsbombpy.api_client import has_auth

print(has_auth({"user": "john", "passwd": "pass"}))  # True
print(has_auth({"user": "", "passwd": "pass"}))      # False, raises warning
print(has_auth({"user": None, "passwd": "pass"}))    # False, raises warning
```

--------------------------------

### Default Credentials Structure

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Python code showing the default credentials structure that uses environment variables.

```python
DEFAULT_CREDS = {
    "user": os.environ.get("SB_USERNAME"),
    "passwd": os.environ.get("SB_PASSWORD"),
}
```

--------------------------------

### lineups()

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/INDEX.md

Retrieves lineup information for matches. Authentication is optional.

```APIDOC
## lineups()

### Description
Retrieves lineup information for matches.

### Function Signature
lineups()

### Parameters
This function does not take any parameters.

### Returns
dict[str, DataFrame] containing lineup data.

### Authentication
Optional
```

--------------------------------

### Work with 360 Tracking Data for a Single Match

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Fetch 360 tracking data for a specific match, providing detailed player observations.

```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}

# Single match
frames = sb.frames(match_id=3837323, creds=creds)
print(f"Total player observations: {len(frames)}")
```

--------------------------------

### Accessing 360 Metrics from Events

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/types.md

Fetches match events including 360 metrics and displays the count of visible teammates and opponents for the first few events.

```python
events_360 = sb.events(match_id=3837323, include_360_metrics=True, creds=creds)
print(events_360[["visible_teammates", "visible_opponents"]].head())
```

--------------------------------

### Fetch Events as Raw Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve match events as a raw Python dictionary. This format allows for more granular access to event data.

```python
from statsbombpy import sb

events = sb.events(match_id=303299, fmt="dict")
print(type(events))  # <class 'dict'>

# Access first event
first_id = list(events.keys())[0]
first_event = events[first_id]
print(first_event["type"]["name"])
```

--------------------------------

### Get Competitions as DataFrame

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competitions.md

Retrieves all available competitions and seasons as a pandas DataFrame. This is useful for exploring the dataset and understanding available options.

```python
from statsbombpy import sb

# Get all competitions as DataFrame
competitions_df = sb.competitions()
print(competitions_df.head())
```

--------------------------------

### Retrieve Matches for a Competition Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-public.md

Fetch a dictionary of matches for a specific competition and season, using their respective IDs. The keys of the returned dictionary are match IDs.

```python
from statsbombpy import public

matches = public.matches(competition_id=9, season_id=42)
print(f"Total matches: {len(matches)}")
```

--------------------------------

### Retrieve Matches for a Competition Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

Fetches matches for a specified competition and season. Requires competition ID, season ID, and credentials.

```python
matches = api_client.matches(competition_id=9, season_id=42, creds=creds)
```

--------------------------------

### StatsBombPy Project File Organization

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/INDEX.md

This snippet illustrates the directory structure of the StatsBombPy project, showing the location of key documentation files and API reference modules.

```text
output/
├── INDEX.md                                    (this file)
├── README.md                                   (main overview)
├── QUICKSTART.md                               (quick start guide)
├── api-index.md                                (complete symbol index)
├── configuration.md                            (config reference)
├── types.md                                    (data type definitions)
├── errors.md                                   (exception reference)
│
├── API Reference Files (Main Functions):
├── api-reference-competitions.md
├── api-reference-matches.md
├── api-reference-lineups.md
├── api-reference-events.md
├── api-reference-competition-events.md
├── api-reference-frames.md
├── api-reference-competition-frames.md
├── api-reference-player-match-stats.md
├── api-reference-player-season-stats.md
├── api-reference-team-match-stats.md
└── api-reference-team-season-stats.md
│
└── API Reference Files (Internal Modules):
    ├── api-reference-api-client.md
    ├── api-reference-public.md
    ├── api-reference-helpers.md
    └── api-reference-entities.md
```

--------------------------------

### Retrieve Lineups for a Match

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

Fetches team lineups for a given match ID. Requires the match ID and authentication credentials.

```python
lineups = api_client.lineups(match_id=12345, creds=creds)
```

--------------------------------

### Check Available Competitions

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve a list of available competitions to verify exact spelling for competition/season combinations. This helps resolve 'KeyError' issues.

```python
comps = sb.competitions()
print(comps[["country_name", "competition_name", "season_name"]].head())
```

--------------------------------

### Get Team Match Statistics

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Fetches aggregated statistics for a team within a specific match. This provides insights into team performance during a single game.

```python
team_match = sb.team_match_stats(3772072)
team_match
```

--------------------------------

### Get Player Season Statistics

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieves aggregated statistics for a player across a specific competition and season. This allows for season-long player performance tracking.

```python
player_season = sb.player_season_stats(competition_id=9, season_id=42)
player_season
```

--------------------------------

### Include 360 Tracking Metrics

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-events.md

Retrieves event data for a match, including 360 tracking metrics. This requires authentication and is useful for detailed spatio-temporal analysis.

```python
# Include 360 tracking metrics (authenticated users only)
events_360 = sb.events(
    match_id=3837323,
    include_360_metrics=True,
    creds={"user": "username", "passwd": "password"}
)
print(events_360[["visible_teammates", "visible_opponents", "line_breaking_pass"]])
```

--------------------------------

### Get All Events for a Match

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-events.md

Retrieves all events for a given match ID and returns them as a single pandas DataFrame. Useful for a comprehensive overview of match events.

```python
from statsbombpy import sb

# Get all events for a match as single DataFrame
events = sb.events(match_id=303299)
print(len(events))  # Total number of events
print(events.columns)  # All available columns
```

--------------------------------

### Open Data Paths Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Dictionary mapping resource types to their respective URLs on GitHub for open data.

```python
OPEN_DATA_PATHS = {
    "competitions": "https://raw.githubusercontent.com/statsbomb/open-data/master/data/competitions.json",
    "matches": "https://raw.githubusercontent.com/statsbomb/open-data/master/data/matches/{competition_id}/{season_id}.json",
    "lineups": "https://raw.githubusercontent.com/statsbomb/open-data/master/data/lineups/{match_id}.json",
    "events": "https://raw.githubusercontent.com/statsbomb/open-data/master/data/events/{match_id}.json",
    "frames": "https://raw.githubusercontent.com/statsbomb/open-data/master/data/three-sixty/{match_id}.json",
}
```

--------------------------------

### Get Team Season Statistics

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieves aggregated statistics for a team across a specific competition and season. This is useful for analyzing team performance over an entire season.

```python
team_season = sb.team_season_stats(competition_id=9, season_id=42)
team_season
```

--------------------------------

### Access Player Match Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieve player statistics for a specific match. Use fmt='dict' for dictionary output.

```python
sb.player_match_stats(3772072, fmt="dict")
```

--------------------------------

### Basic StatsBombPy Queries

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/INDEX.md

Use these functions for basic data retrieval without requiring authentication. They fetch competition, match, lineup, and event data, returning results in a DataFrame format.

```python
sb.competitions(fmt="dataframe", creds=DEFAULT_CREDS)
```

```python
sb.matches(competition_id, season_id, fmt="dataframe", creds=DEFAULT_CREDS)
```

```python
sb.lineups(match_id, fmt="dataframe", creds=DEFAULT_CREDS)
```

```python
sb.events(match_id, split=False, filters={}, fmt="dataframe", 
          flatten_attrs=True, creds=DEFAULT_CREDS, include_360_metrics=False)
```

--------------------------------

### Work with 360 Tracking Data for an Entire Competition

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/README.md

Retrieve 360 tracking data for an entire competition across a specified season.

```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}

# Entire competition
comp_frames = sb.competition_frames(
    country="Europe",
    division="Champions League",
    season="2022/2023",
    creds=creds
)
```

--------------------------------

### Get Dribble Events DataFrame

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieves a DataFrame containing only dribble events for a given match ID. Set flatten_attrs to False to keep event attributes in their own columns.

```python
sb.events(match_id=303299, split=True, flatten_attrs=False)["dribbles"]
```

--------------------------------

### Accessing Frame Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/types.md

Fetches 360-degree tracking data for a match and displays the player name, team, and location for the first few observations.

```python
frames = sb.frames(match_id=3837323, creds=creds)
print(f"Total observations: {len(frames)}")
print(frames[["player_name", "team", "location"]].head())
```

--------------------------------

### Get All Events from a Season

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve all events for a given country, division, and season. This function utilizes parallel processing for efficiency and may take some time for large seasons.

```python
from statsbombpy import sb

# This uses parallel processing automatically
all_events = sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020"
)

print(f"Total events in season: {len(all_events)}")
print(f"Event types: {all_events['type'].unique()}")
```

--------------------------------

### Perform HTTP Basic Authentication

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-api-client.md

This snippet shows how to perform HTTP Basic Authentication for an API request. It constructs an `HTTPBasicAuth` object using user credentials and passes it to the `req.get` method.

```python
auth = req.auth.HTTPBasicAuth(creds["user"], creds["passwd"])
resp = req.get(url, auth=auth)
```

--------------------------------

### Define Credentials Dictionary

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/configuration.md

Structure for passing authentication credentials directly to functions.

```python
creds = {
    "user": "your_username",
    "passwd": "your_password"
}
```

--------------------------------

### Accessing Team Match Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/types.md

Demonstrates how to retrieve and display specific columns from a team match statistics DataFrame. Ensure you have valid credentials and a match ID.

```python
stats = sb.team_match_stats(match_id=303299, creds=creds)
print(stats[["team", "possession", "shots", "passes"]].head())
```

--------------------------------

### Get 360 Frames as JSON

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-frames.md

Retrieves 360 tracking data for a match in raw JSON format. This is useful for accessing the data structure directly. Requires authentication.

```python
# Get raw JSON format
frames_json = sb.frames(
    match_id=3837323,
    fmt="json",
    creds={"user": "username", "passwd": "password"}
)
first_frame = frames_json[0]
print(f"Event UUID: {first_frame['event_uuid']}")
print(f"Visible area: {first_frame['visible_area']}")
```

--------------------------------

### Access Matches Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieve matches for a specific competition and season. Use fmt='dict' for dictionary output.

```python
sb.matches(competition_id=9, season_id=42, fmt="dict")
```

--------------------------------

### Get Team Match Statistics

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/QUICKSTART.md

Retrieve team statistics for a specific match, requiring API credentials. This provides insights into team performance metrics such as possession, passes, and shots.

```python
from statsbombpy import sb

creds = {"user": "username", "passwd": "password"}

stats = sb.team_match_stats(match_id=303299, creds=creds)
print(stats[["team", "possession", "passes", "shots", "shots_on_target"]])
```

--------------------------------

### Get Raw JSON Event Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-events.md

Retrieves event data for a match in raw JSON format. This is useful for accessing the original structure of the event data as provided by the API.

```python
# Get raw JSON format
events_json = sb.events(match_id=303299, fmt="json")
first_event = events_json[list(events_json.keys())[0]]
print(first_event["type"]["name"])
```

--------------------------------

### matches()

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/INDEX.md

Retrieves match data for a given competition. Authentication is optional.

```APIDOC
## matches()

### Description
Retrieves match data for a given competition.

### Function Signature
matches()

### Parameters
This function does not take any parameters.

### Returns
DataFrame or dict containing match data.

### Authentication
Optional
```

--------------------------------

### Import StatsBombPy Module

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-index.md

Import the main StatsBombPy module for accessing its functions. All exported functions are accessed via the 'sb' object.

```python
from statsbombpy import sb
```

--------------------------------

### Access Player Season Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieve player statistics for a specific competition and season. Use fmt='dict' for dictionary output.

```python
sb.player_season_stats(competition_id=9, season_id=42, fmt="dict")
```

--------------------------------

### Get Team Season Stats (JSON)

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-team-season-stats.md

Retrieves aggregated team statistics for a competition season in raw JSON format. This is useful when direct processing of API response objects is needed.

```python
# Get raw JSON
stats_json = sb.team_season_stats(
    competition_id=9,
    season_id=42,
    fmt="json",
    creds=creds
)
```

--------------------------------

### Access Team Match Stats

Source: https://github.com/statsbomb/statsbombpy/blob/master/README.md

Retrieve team statistics for a specific match. Use fmt='dict' for dictionary output.

```python
sb.team_match_stats(3772072, fmt="dict")
```

--------------------------------

### Index Competitions by Composite Key

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-entities.md

Transforms a list of competition objects into a dictionary indexed by a composite key of (country_name, competition_name, season_name, competition_gender). Useful for quick lookups of competition details.

```python
from statsbombpy.entities import competitions

raw = [
    {
        "country_name": "Germany",
        "competition_name": "1. Bundesliga",
        "season_name": "2019/2020",
        "competition_gender": "male",
        "competition_id": 9,
        ...
    },
    ...
]

indexed = competitions(raw)
comp = indexed["Germany", "1. Bundesliga", "2019/2020", "male"]
print(comp["competition_id"])  # 9
```

--------------------------------

### Get Events with 360 Metrics

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competition-events.md

Retrieves event data including 360 tracking metrics for a competition season. This feature requires API authentication and is typically available for subscribed users.

```python
# With 360 metrics (for subscribed users)
events_360 = sb.competition_events(
    country="Europe",
    division="Champions League",
    season="2022/2023",
    include_360_metrics=True,
    creds={"user": "username", "passwd": "password"}
)
```

--------------------------------

### Retrieve Lineup Data

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/types.md

Fetches team lineup data for a match as a dictionary, keyed by team name. Displays player name and jersey number.

```python
lineups = sb.lineups(match_id=303299)
frankfurt = lineups["Eintracht Frankfurt"]
print(frankfurt[["player_name", "jersey_number"]])
```

--------------------------------

### Get Raw JSON Format for Competition Frames

Source: https://github.com/statsbomb/statsbombpy/blob/master/_autodocs/api-reference-competition-frames.md

Retrieves 360-degree tracking data in raw JSON format for a specified competition season. This is useful for custom parsing or when a pandas DataFrame is not desired.

```python
# Get raw JSON format
frames_json = sb.competition_frames(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020",
    fmt="json",
    creds=creds
)
```
Tokens:
Raw