DOCSEARCHbyAlgolia
Submit Docs

statsbombpy

repository·master·Indexed 20 days ago

https://github.com/statsbomb/statsbombpy

A Python package for streaming StatsBomb football data, supporting both free open data and authenticated API access for paying customers. It provides functions to retrieve competitions, matches, team lineups, and detailed event data as pandas DataFrames. Features include support for 360 metrics, competition-wide event queries, and frame data retrieval, with configurable concurrency via the SB_CORES environment variable.

Tokens
4.2K
Snippets
13
Records
19
Agent score
23%

What's inside statsbombpy

  2. Understand the structure of Event data

    master

    The events data returned by statsbombpy is provided as a pandas DataFrame. Each row represents a specific event in a match, and columns contain various attributes describing the event.

    Key event attributes include:

    • Identifiers: id, match_id, player, team.
    • Temporal Data: minute, second, timestamp.
    • Spatial Data: location (coordinates), pass_end_location, shot_end_location, goalkeeper_end_location.
    • Event Details: type (e.g., Pass, Shot, Recovery), play_pattern (e.g., Regular Play), possession_team.
    • Action-Specific Metadata:
      • Passes: pass_type, pass_outcome, pass_body_part, pass_length, pass_height.
      • Shots: shot_outcome, shot_statsbomb_xg, shot_technique, shot_type.
      • Goalkeeping: goalkeeper_type, goalkeeper_technique, goalkeeper_position.
      • Duels/Recoveries: duel_type, duel_outcome, ball_recovery_offensive.

    Note that many columns will contain NaN values because they are specific to certain event types (e.g., a Pass event will not have shot_statsbomb_xg).

  3. Include 360 metrics in event data

    master

    If you have a data subscription that includes 360 data for a competition, you can include advanced metrics (such as line-breaking pass data) by setting include_360_metrics=True in the events() or competition_events() functions.

    Note: 360 metrics are not available in the Open Data; they are only accessible to customers with a valid data subscription.

  4. Access raw JSON data as Python dictionaries

    master

    By default, statsbombpy returns data in preprocessed formats (like pandas DataFrames). If you need to access the raw data without any preprocessing, you can pass fmt="dict" to the API methods. This returns the entities as Python dictionaries, serving as a direct interface to the raw JSON files.

    # Examples of accessing raw data

# Competitions
sb.competitions(fmt="dict")

# Matches
sb.matches(competition_id=9, season_id=42, fmt="dict")

# Lineups
sb.lineups(match_id=303299, fmt="dict")

# Events
sb.events(303299, fmt="dict")

# Competition-wide events
sb.competition_events(
    country="Germany",
    division="1. Bundesliga",
    season="2019/2020",
    gender="male",
    fmt="dict"
)

# Frames
sb.frames(3772072, fmt="dict")

# Competition-wide frames
sb.competition_frames(
    country="Germany",
    division="1. Bundesliga",
    season="2021/2022",
    gender="male",
    fmt="dict"
)

# Player Match Stats
sb.player_match_stats(3772072, fmt="dict")

# Player Season Stats
sb.player_season_stats(competition_id=9, season_id=42, fmt="dict")

# Team Match Stats
sb.team_match_stats(3772072, fmt="dict")

# Team Season Stats
sb.team_season_stats(competition_id=9, season_id=42, fmt="dict")

  6. Configure concurrency with SB_CORES

    master

    To speed up sb.competition_events() and sb.competition_frames(), you can control the number of CPU cores used by setting the SB_CORES environment variable.

    Default Behavior:

    • If SB_CORES is set, the library uses that number of cores.
    • If SB_CORES is not set, the library attempts to detect your system's cores and uses (detected_cores - 2).
    • If detection fails, it defaults to 4 cores.

  7. Authenticate with the StatsBomb API

    master

    API access is reserved for paying customers. You can authenticate using one of two methods:

    1. Environment Variables

    Set the following environment variables in your system to avoid passing credentials in your code:

    • SB_USERNAME
    • SB_PASSWORD

    2. Manual Credentials

    Pass a creds dictionary directly to functions. The dictionary must follow this format: {"user": "YOUR_USERNAME", "passwd": "YOUR_PASSWORD"}

  8. Retrieve Aggregated Stats

    master

    For customers with access, StatsBomb provides aggregated statistics at various granularities. You can retrieve these using the following methods:

    • sb.player_match_stats(match_id): Player-level stats for a specific match.
    • sb.player_season_stats(competition_id, season_id): Player-level stats for a specific season.
    • sb.team_match_stats(match_id): Team-level stats for a specific match.
    • sb.team_season_stats(competition_id, season_id): Team-level stats for a specific season.
    player_match = sb.player_match_stats(3772072)
player_season = sb.player_season_stats(competition_id=9, season_id=42)
team_match = sb.team_match_stats(3772072)
team_season = sb.team_season_stats(competition_id=9, season_id=42)

  9. Retrieve matches for a specific competition and season

    master

    Use sb.matches(competition_id, season_id) to retrieve a DataFrame of matches for a given competition and season.

    Parameters:

    • competition_id: The unique identifier for the competition.
    • season_id: The unique identifier for the season.

    The resulting DataFrame contains match metadata including match_id, match_date, home_team, away_team, home_score, away_score, stadium, and various fidelity versions for data and coordinates.

    from statsbombpy import sb

matches = sb.matches(competition_id=9, season_id=42)

  10. Retrieve match events

    master

    Use sb.events(match_id) to retrieve all event data for a specific match. By default, this returns a single DataFrame containing all event types and their associated attributes.

    from statsbombpy import sb

events = sb.events(match_id=303299)

  11. Retrieve all available competitions

    master

    Use sb.competitions() to get a list of all available competitions. The returned DataFrame includes details such as competition_id, season_id, country_name, competition_name, competition_gender, season_name, and availability timestamps.

    from statsbombpy import sb

competitions = sb.competitions()

  12. Retrieve 360 Frame data

    master

    The frame functions return raw 360 freeze frame data, including the visible area for each frame. Note that data is returned at the player level, meaning you will receive multiple rows per frame/event_id (one for each player in the frame).

    Use sb.frames() to retrieve frames for a specific match, or sb.competition_frames() to retrieve frames for an entire competition based on country, division, and season.

    # Get frames for a specific match
match_frames = sb.frames(match_id=3772072, fmt='dataframe')

# Get frames for a specific competition
comp_frames = sb.competition_frames(
    country="Germany",
    division= "1. Bundesliga",
    season="2019/2020"
)