How statsbomb/open-data works
1. This repository is a static data distribution repo, not an application. Its purpose is to publish StatsBomb football data as versioned JSON files for research and analysis.
2. The top-level data/ directory is the core product. It contains the canonical datasets exported from the StatsBomb Data API and organized by entity type rather than by software subsystem.
3. data/competitions.json is the entry index. It defines the available competitions and seasons and acts as the first lookup layer for navigating the rest of the dataset.
4. data/matches/ is the competition/season hierarchy. Each subfolder is a competition ID, and each file inside is a season ID. This is the bridge between the competition catalog and match-level records.
5. data/events/ is match-centric event data. Each JSON file is named by match ID and stores the event timeline for that match. This is typically the richest behavioral dataset in the repo.
6. data/lineups/ mirrors data/events/ at the same match-ID granularity. For each match, it provides squad and player lineup information that complements the event stream.
7. data/three-sixty/ contains StatsBomb 360 frame data for selected matches only. It is also keyed by match ID, but it is a sparse augmentation layer rather than a complete parallel dataset.
8. The main data flow is hierarchical: competition/season metadata in competitions.json points to match lists, and match IDs then join together events, lineups, and sometimes 360-frame data. The match ID is the primary foreign key across the repository.
9. The doc/ directory contains PDF specifications and format documentation for each dataset type. These documents define the schema and semantics needed to interpret the JSON correctly.
10. README.md is the public entry point and explains the dataset layout and usage conventions. LICENSE.pdf and the usage terms in the README define distribution and attribution boundaries.
11. img/ appears to be a supporting asset folder, likely for branding or documentation, but it is not part of the data model itself.
12. Because there is no executable code, build pipeline, or service layer in the repository, the architecture diagram should emphasize storage, dataset relationships, and documentation rather than runtime components.
Main entry points: README.md README · matches Matches · events Events · StatsBomb Open Data Specification v1.1.pdf Spec Guide
Components 14
Repository
Static StatsBomb open data distribution
Data
Canonical versioned JSON datasets
- Competitions · Entry index of competitions and seasons
data/competitions.json - Matches · Competition and season hierarchy keyed by IDs
data/matches - Events · Match-level event timelines
data/events - Lineups · Match-level squad and player lineups
data/lineups - 360 Frames · Selected-match 360 frame augmentations
data/three-sixty
Docs
PDF specifications and usage guidance
- Spec Guide · Repository-wide specification reference
doc/StatsBomb Open Data Specification v1.1.pdf - Competitions PDF · Competition and season schema documentation
doc/Open Data Competitions v2.0.0.pdf - Matches PDF · Matches dataset schema documentation
doc/Open Data Matches v3.0.0.pdf - Events PDF · Events dataset schema documentation
doc/Open Data Events v4.0.0.pdf - Lineups PDF · Lineups dataset schema documentation
doc/Open Data Lineups v2.0.0.pdf - 360 PDF · 360 frames dataset schema documentation
doc/Open Data 360 Frames v1.0.0 (1).pdf
Connections 23
- README → Competitions: describes · Explains the main data entry point
- README → Matches: documents · Explains dataset layout and navigation
- README → Events: documents · Explains match event data
- README → Lineups: documents · Explains match lineup data
- README → 360 Frames: documents · Explains 360 frame data
- License → README: governs · Defines distribution and attribution terms
- Competitions → Matches: indexes · Competition and season metadata points to match lists
- Matches → Events: joins to · Match IDs bridge into match event records
- Matches → Lineups: joins to · Match IDs bridge into lineups
- Matches → 360 Frames: joins to · Match IDs bridge into sparse 360 frames
- Events → Lineups: complements · Lineups augment the event stream at match level
- Events → 360 Frames: augmented by · Some matches have 360 frame data alongside events
- Spec Guide → Competitions: specifies · General schema and semantics reference
- Spec Guide → Matches: specifies · General schema and semantics reference
- Spec Guide → Events: specifies · General schema and semantics reference
- Spec Guide → Lineups: specifies · General schema and semantics reference
- Spec Guide → 360 Frames: specifies · General schema and semantics reference
- Competitions PDF → Competitions: documents · Competition dataset format
- Matches PDF → Matches: documents · Matches dataset format
- Events PDF → Events: documents · Events dataset format
- Lineups PDF → Lineups: documents · Lineups dataset format
- 360 PDF → 360 Frames: documents · 360 frames dataset format
- Assets → README: supports · Supporting assets for presentation or docs