StatsBomb publishes a free, detailed open dataset: as of 20 October 2026, 3,961 matches across 80 competition-seasons and 24 distinct competitions, including every match of the 2018 and 2022 World Cups. One Python package reads it, with no API key. It is not a random sample of football, though. About one match in six comes from a season the data follows through a single team, most of it Barcelona's, and only 426 matches carry the 360 player-position frames. This guide goes from pip install to a top-xG leaderboard, maps what the free data covers, and shows the one filter that most first leaderboards forget.
Installation
Two libraries carry the load: statsbombpy, StatsBomb's official Python client, and pandas for the usual wrangling. Add matplotlib if you want charts.
pip install statsbombpy matplotlib pandas
That is the entire setup. The client's own documentation says the open data "can be accessed without the need of authentication": it reads StatsBomb's public GitHub-hosted JSON files, so nothing lives on your machine until you ask for it. The latest release on 20 October 2026 was v1.22.0, published on 30 July 2026. StatsBomb does ask users to register their interest on its website (more on the terms below), but no key or login is involved.
from statsbombpy import sb
The data model: competitions → matches → events
StatsBomb organises everything in layers, and understanding them up front saves a lot of confused index errors. The repository's README lists four folders: competitions.json, matches/ (one folder per competition, one file per season), events/ and lineups/ (one file per match), plus three-sixty/ for the matches that have 360 frames.
Competitions. The outermost layer. Calling sb.competitions() returns a DataFrame with one row per competition-season: the 2022 World Cup is one row, the 2018 World Cup is another. On 20 October 2026 the file had 80 such rows across 24 distinct competitions.
Matches. Once you have a competition-season you can call sb.matches(competition_id=..., season_id=...) to get its matches. The 2022 World Cup returns 64 rows, one per match, each carrying kick-off time, final score, home and away team names, the competition stage, and a match_id you'll use for the next step.
Events. The real payload. sb.events(match_id=...) returns every on-ball action in a single match: passes, shots, carries, duels, goalkeeper actions, set pieces. The 2022 final alone has 4,407 events. Each event has a type, a team, a player, a location, a period, a timestamp, and a cluster of type-specific columns: pass_end_location for passes, shot_statsbomb_xg for shots, and so on.
Lineups and 360 frames. sb.lineups(match_id=...) returns each team's players (the raw lineup files also list every player's positions and cards), and sb.frames(match_id=...) returns the 360 freeze frames where they exist. Both are covered below.
What the free data covers, match by match
The competitions list makes the free data look broad: Champions League, La Liga, the Premier League, Serie A, two World Cups. Counting the matches behind each row tells a narrower story. We read all 80 match files on 20 October 2026 and counted, for each competition-season, how many matches it holds, how many carry 360 frames, and whether one team appears in every match.
Five things stand out:
- 670 matches (16.9%) come from seasons that follow one team. In those seasons the same club is in every match. Barcelona alone accounts for 486 of them (12.3% of everything): 16 La Liga seasons from 2004/05 to 2020/21 (2015/16, the one complete La Liga season, is the exception), from 7 matches in the first to 38 in 2014/15. Paris Saint-Germain (2021/22 and 2022/23, 58 matches) and Inter Miami (2023, 6 matches) follow, so 550 club matches come from those three clubs' seasons. We checked 56 of their lineups (all of Barcelona 2004/05 and 2005/06, PSG 2021/22 and Inter Miami 2023), and Lionel Messi is in the lineup with a position in every one. The remaining one-team seasons are Bayer Leverkusen's (34 Bundesliga matches in 2015/16 and 34 in 2023/24, the only Bundesliga data in the set) and Arsenal's 38 league matches of 2003/04.
- The Premier League is two seasons. All 380 matches of 2015/16 and Arsenal's 38 from 2003/04. Nothing more recent.
- 2015/16 is the one complete big-league season. La Liga, the Premier League and Serie A have all 380 matches each, Ligue 1 has 377, and the Bundesliga has only Leverkusen's 34.
- The Champions League is 18 single matches. One per season from 1970/71 to 2018/19, 17 of them finals (the other is a 1999/2000 first-round match). The six older men's World Cups (1958 to 1990) add 19 matches between them, while 2018 and 2022 are complete at 64 each. There is no 2026 season of anything: the 2026 World Cup is not in the free data.
- The women's game is a third of the set. 1,310 of the 3,961 matches are women's matches against 2,651 men's, including four WSL seasons (457 matches), both recent Women's Euros and the 2019 and 2023 Women's World Cups. In all, 512 matches come from international tournaments.
The practical rule: the free data is excellent for learning the methods and for studying the tournaments it covers in full, but a "La Liga" average built from 2004/05 to 2020/21 is a Barcelona average, and a Bundesliga one is a Leverkusen one. Before you generalise, check what you loaded. These lines reproduce the count:
rows = []
for c in sb.competitions().itertuples():
m = sb.matches(competition_id=c.competition_id, season_id=c.season_id)
teams = [set(p) for p in zip(m.home_team, m.away_team)]
in_every = set.intersection(*teams) if len(m) > 1 else set()
rows.append((c.competition_name, c.season_name, len(m), ", ".join(in_every)))
coverage = pd.DataFrame(rows, columns=["competition", "season", "matches", "team_in_every_match"])
That is 80 small requests. On 20 October 2026 it returns 3,961 matches in total, and a non-empty team_in_every_match on every season listed above.
Loading competitions, then drilling down
The competition call is the starting point for almost every analysis. It is free and fast: it fetches one small JSON file.
from statsbombpy import sb
import pandas as pd
# 1 - what's available? competitions() returns one row per competition-season.
comps = sb.competitions()
print(f"{len(comps)} competition-seasons available, "
f"{comps.competition_name.nunique()} distinct competitions.")
On 20 October 2026 this prints 80 competition-seasons available, 24 distinct competitions. The 2022 World Cup is competition_id 43, season_id 106.
# 2 - pick a competition-season (men's 2022 World Cup) and list its matches.
season = comps[(comps.competition_id == 43) & (comps.season_name == "2022")].iloc[0]
matches = sb.matches(competition_id=43, season_id=int(season.season_id))
print(f"{len(matches)} matches at the 2022 World Cup.")
That prints 64 matches at the 2022 World Cup.: every group-stage game through the final. Each row contains both team names, the final score, and the match_id needed for the next step.
Pulling shots across a whole tournament
Calling sb.events() once per match and concatenating the results is the standard pattern for tournament-level analysis. It takes a minute or two on a normal connection (each match is a separate HTTP request), and it is straightforward:
# 3 - pull events for every match, keep the shots, drop the penalty shootouts.
shots = []
for match_id in matches.match_id:
ev = sb.events(match_id=int(match_id))
shots.append(ev[ev.type == "Shot"])
shots = pd.concat(shots, ignore_index=True)
shots = shots[shots.period != 5] # period 5 = the penalty shootout
shots["xg"] = shots.shot_statsbomb_xg.astype(float)
The explicit astype(float) is worth explaining: shot_statsbomb_xg comes back as a mixed-type column because StatsBomb stores non-shot events in the same DataFrame with nulls in shot-specific columns. Casting it after filtering to shots avoids the occasional coercion warning downstream.
The shootout trap
The period != 5 line is the one most first leaderboards miss, and the first version of this page missed it too. StatsBomb records a penalty shootout as period 5, and every kick in it is a Shot event with an xG value and an outcome, exactly like a shot in open play. The 2022 World Cup had five shootouts with 41 shootout kicks between them, by 37 players. Left in, they add 26 "goals" that never counted in any match and 32.12 xG, because StatsBomb gives every penalty the same value, 0.7835, whether it comes in the 20th minute or in a shootout. Of the 195 shots marked as goals in the 2022 file, 169 are real match goals.
The kicks then pile onto a few names. Messi took two shootout kicks (against the Netherlands and France) and scored both, which adds 1.57 xG and two goals he never scored in a match. Lautaro Martínez scored his kick in the shootout against the Netherlands, enough to give him a "goal" at a tournament where he scored none in a match. Nikola Vlašić took two kicks for Croatia and drops out of the top ten without them. If you want penalties at all, the cleaner split is the one we use on the shootout discount: 23 in-play penalties (17 scored) and the 41 shootout kicks, measured separately.
From here, building the leaderboard is one line of pandas groupby:
# 4 - the ten players with the most expected goals (shootouts already dropped).
top = shots.groupby("player").xg.sum().sort_values(ascending=False).head(10).round(2)
goals = shots[shots.shot_outcome == "Goal"].groupby("player").size()
The goals Series counts actual goals for the same players, which is what makes the output interesting: comparing xG to actual goals shows who finished above their chances and who left them on the pitch.
Building the chart
A horizontal bar chart works better than a vertical one here because the player names are long. Highlight the top bars to pull the eye, and print both xG and goals on each bar so readers don't have to cross-reference a table. A minimal matplotlib version:
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(8.8, 5.6))
names = list(top.index)[::-1] # reverse so the highest is at the top
vals = list(top.values)[::-1]
colors = ["#C9A227" if v >= sorted(vals)[-2] else "#0F5132" for v in vals]
ax.barh(names, vals, color=colors)
for i, (n, v) in enumerate(zip(names, vals)):
ax.text(v, i, f" {v:.2f} xG ({int(goals.get(n, 0))} goals)", va="center", fontsize=9)
ax.set_xlabel("Expected goals (xG), penalty shootouts excluded")
ax.set_title("Most xG at the 2022 World Cup", loc="left", fontweight="bold")
ax.spines[["top", "right"]].set_visible(False)
ax.margins(x=0.25)
fig.text(0.01, 0.01, "Data: StatsBomb open data", fontsize=8)
fig.savefig("statsbomb-top-xg-wc2022.png", dpi=150, bbox_inches="tight")
Reading the leaderboard
Here is the top ten, drawn directly from the data:
| Player | xG | Goals |
|---|---|---|
| Lionel Andrés Messi Cuccittini | 6.03 | 7 |
| Kylian Mbappé Lottin | 4.23 | 8 |
| Robert Lewandowski | 3.13 | 2 |
| Olivier Giroud | 3.04 | 4 |
| Breel-Donald Embolo | 2.39 | 2 |
| Harry Kane | 2.33 | 2 |
| Neymar da Silva Santos Junior | 2.13 | 2 |
| Lautaro Javier Martínez | 2.12 | 0 |
| Cristiano Ronaldo dos Santos Aveiro | 1.94 | 1 |
| Enner Remberto Valencia Lastra | 1.92 | 3 |
Messi leads with 6.03 xG and 7 goals, but penalties drive much of it: he took five in matches and scored four, and at 0.7835 each those five are 3.92 of his xG, leaving 2.11 from everything else. Mbappé scored 8 from 4.23 xG; two of those were penalties, so his other six goals came from 2.67 xG of chances, the clearest finishing run at the tournament. Lewandowski's 3.13 xG and 2 goals include two penalties, one scored and one saved; Poland went out to France, 3-1, in the Round of 16. Lautaro Martínez is the hard-luck entry: 2.12 xG from 14 shots in matches and no goal.
Two habits make a table like this honest. Report penalties separately, or show a non-penalty column next to the total, because one penalty is worth more xG than most players' open-play chances across a whole group stage. And read xG against goals as a description of one tournament, not a verdict on finishing skill: over seven matches the gaps are mostly noise. Our expected goals explainer covers why.
360 frames: what you get for free
Twelve competition-seasons, 426 matches in all, carry StatsBomb 360 data: a freeze frame for most events that marks every player visible in the broadcast footage at that moment, teammate or opponent, plus the visible area of the pitch. The 360 matches are all from 2020/21 onward: the 2022 men's and 2023 women's World Cups, Euro 2020 and 2024, the 2022 and 2025 Women's Euros, one 2023 Africa Cup of Nations match, and some of the one-team club seasons (Barcelona 2020/21, PSG's two, Leverkusen 2023/24, Inter Miami 2023). 293 of the 426 are international matches.
For the 2022 final, the 360 file holds 3,683 frames for the match's 4,407 events: 83.6% of events have a frame. A frame shows 16.7 players on average, and anywhere from 1 to 21, because it only sees what the camera saw. Loading it takes one call:
frames = sb.frames(match_id=3869685, fmt="dataframe") # the 2022 final
# one row per visible player per event; join to events on the event id
Two limits to know. The frames are positions only: the client's documentation says the derived 360 metrics (line-breaking passes and the like) are not in the open data and need a paid subscription. And because a frame only holds the players on screen, "nobody near the shooter" can mean "nobody in shot". The mplsoccer tutorial shows how to draw StatsBomb coordinates on a pitch, which is the first thing you will want to do with a frame.
The terms: what StatsBomb's user agreement says
The data is free to download, but it is not public-domain or openly licensed. The repository's README asks anyone who publishes, shares or distributes research based on it to "state the data source as StatsBomb and use our logo". The repository's licence file is a user agreement (the version we read on 20 October 2026 is dated "last updated 8 September 2023"). In summary:
- The data is offered as "a research tool", for analysis, research and shared understanding of the game, and StatsBomb asks users to register their interest on its website.
- Clause 1.2.1: users may not edit, distort, distribute, reproduce, sell or otherwise provide the data to a third party.
- Clause 1.2.2: users may not commercially exploit the data or any analysis derived from it.
- Clause 1.4: any publication of analysis formed from StatsBomb data must be credited with the StatsBomb brand logo.
- StatsBomb can withdraw the service at any time, and the data comes "as is", with no warranty of accuracy or completeness.
This is a summary, not legal advice. Read the agreement in the repository yourself before you publish anything, and especially before any commercial use. Credit StatsBomb on every chart and in the write-up around it.
Where to go next
Once you are comfortable pulling shots you are a short step from most of the standard analyses in football analytics:
- Filter events to
type == "Pass"and uselocationandpass_end_locationto draw a pass map: the mplsoccer tutorial on this site covers that exactly. - Track xG round by round instead of in one total: build a tournament xG tracker uses the same shot table.
- Group events by
periodto study how a team's pressing intensity changes as a match ages, and remember that period 5 is the shootout. - Pull the
shot_freeze_framecolumn from shot events to see where the defence was standing at the moment of each shot. It is part of the event data, separate from the 360 files: in the 2022 final all 27 non-penalty shots carry one. - Compare StatsBomb's free release with the other free sources in every free soccer data source, ranked, especially if you need league seasons it doesn't cover.
Run the code blocks above top to bottom in one file. Change the competition_id and season_id and the same lines work for any of the 80 competition-seasons, as long as you check the coverage first.
The data behind this piece
- StatsBomb open data:
competitions.json, all 80 match files, 56 lineup files and the 2022 final's 360 file, retrieved 20 October 2026 and counted by our pull script. The repository's README and user agreement were read the same day; thedocfolder holds the event, match, lineup and 360 specifications. - The 2022 World Cup shots: every shot of all 64 matches, pulled from the same repository in June 2026; the event files are in StatsBomb’s open-data repository.
- statsbombpy: the official Python client, its README (open-data access,
frames(), the 360-metrics note) and its release list, read 20 October 2026. - StatsBomb: the company behind the data, and the destination for the credit the terms ask for.
- mplsoccer documentation: the plotting library that turns StatsBomb coordinates into pitch visualisations.
- Every number above is recomputed with asserts by our chart script, which also draws both charts.
Published by SoccerAnalytics from public data and the sources named in this piece. How this site is made.