statsbombpy

What it is and what it does

StatsBombpy is a Python client for StatsBomb's football analytics platform. It retrieves structured match, event, lineup, and competition data and returns it as pandas DataFrames, making it easy to load StatsBomb datasets into analysis workflows. The package supports both authenticated API access (for paying customers) and free public datasets hosted on GitHub.

The package handles authentication via environment variables or inline credentials, supports parallel event and frame fetching across multiple CPU cores (configurable via SB_CORES), and includes caching via requests-cache to reduce redundant API calls. Its main dependencies are pandas for data structures, requests for HTTP communication, and joblib for concurrent processing.

Use it for:

• Fetch competition and match metadata for a specific league and season to build a fixture list for analysis.
• Download event-level data (passes, shots, fouls, etc.) for a single match and analyze player actions or team tactics.
• Retrieve lineup data to cross-reference player IDs, positions, and physical attributes with event records.
• Batch download events across multiple matches using parallel processing to speed up large dataset assembly.
• Combine StatsBomb data with external sources (team stats, player ratings) in a pandas workflow for custom analytics.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Streams StatsBomb football analytics data into Python via API (for paying customers) or free public datasets from GitHub, returning structured match, event, lineup, and competition information as pandas DataFrames.

Yes, if you have StatsBomb API credentials or want to use its free public datasets. Install friction is low, maintenance is active, and no known vulnerabilities exist. The main caveat is unclear licensing—verify the User Agreement and data usage terms before publishing research or deploying in production. Python version support is unspecified, so test compatibility with your environment.

Install

statsbombpy on PyPI

pip install statsbombpy

uv add statsbombpy

poetry add statsbombpy

Installing statsbombpy

Before you install

Low friction: pure Python wheel with five common runtime dependencies (pandas, requests, requests-cache, inflect, joblib). Active maintenance—last commit 2026-07-30, 15 days old—and 738 GitHub stars suggest ongoing support.

License in practice

License treatment is unclear; no SPDX or raw license metadata is available. Users should verify licensing terms, especially the StatsBomb User Agreement referenced in the package documentation, before using data in production or publishing research.

Quickstart

pip install statsbombpy

from statsbombpy import sb

# Free public data, no credentials needed
competitions_df = sb.competitions()
matches_df = sb.matches(competition_id=9, season_id=42)
events_df = sb.events(match_id=303299)

API access requires StatsBomb paid credentials (SB_USERNAME and SB_PASSWORD environment variables or creds dict argument); free data is available without authentication.

Verify before relying

• Whether free public data access requires email registration or has usage restrictions beyond the User Agreement.
• Python version compatibility (requires_python is unspecified in metadata).
• Whether the package's concurrency features (SB_CORES environment variable) scale predictably with system resources.

Package facts

Evidence: statsbombpy-1.22.0-py3-none-any.whl

Tags

More Information Analysis packages