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.

Correction, 20 October 2026
The leaderboard first published here counted penalty-shootout kicks as shots, although its caption said shootouts were excluded. That added 41 kicks, 26 "goals" and 32.12 xG to the tournament and moved Lionel Messi from 7 goals to 9 and Kylian Mbappé from 8 to 9. The table, the chart and the code below now drop the shootout rows. The old text also said Poland went out in the group stage; Poland reached the Round of 16 and lost 3-1 to France.

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.

Coordinate convention
StatsBomb maps every event onto a 120×80 pitch, measured in yards. The origin (0, 0) is the bottom-left corner of the pitch as drawn. The attacking direction is always toward x = 120: StatsBomb flips coordinates so the team in possession is always going right. When you plot data from two different teams in the same match without accounting for this, everything lands in the wrong half.

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.

Horizontal bar chart of matches in StatsBomb's free open data by competition, as of 20 October 2026, with the number of seasons in brackets. La Liga 867 matches over 18 seasons, 486 of them Barcelona's matches only; FA Women's Super League 457; Ligue 1 435; Premier League 418; Serie A 381; Liga F 240; NWSL 173; FIFA World Cup 147; then smaller competitions down to single matches. Champions League is 18 single matches. 670 matches come from seasons that follow one team, and 426 carry 360 frames.
Matches in StatsBomb's free data by competition, split into seasons with many teams, seasons that follow one team, and single matches. Data: StatsBomb open data, competitions.json and all 80 match files, retrieved 20 October 2026.

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")
Bar chart of the ten players with the most expected goals at the 2022 World Cup with penalty shootouts excluded: Lionel Messi 6.03 xG and 7 goals, Kylian Mbappé 4.23 and 8, Robert Lewandowski 3.13 and 2, Olivier Giroud 3.04 and 4, Breel Embolo 2.39 and 2, Harry Kane 2.33 and 2, Neymar 2.13 and 2, Lautaro Martínez 2.12 and 0, Cristiano Ronaldo 1.94 and 1, Enner Valencia 1.92 and 3. Dashed outlines show the larger totals that shootout kicks would add for Messi (1.57 xG, 2 goals), Mbappé and Lautaro Martínez (0.78 xG, 1 goal each).
The ten players with the most xG at the 2022 World Cup, penalty shootouts excluded; the dashed outlines show what leaving the shootout kicks in would add. Drawn in this site's chart style from the same numbers the code above produces. Data: StatsBomb open data, all 64 matches.

Reading the leaderboard

Here is the top ten, drawn directly from the data:

Top ten players by total xG at the 2022 FIFA World Cup (all 64 matches, extra time included, penalty shootouts excluded). Data: StatsBomb open data.
Player xG Goals
Lionel Andrés Messi Cuccittini6.037
Kylian Mbappé Lottin4.238
Robert Lewandowski3.132
Olivier Giroud3.044
Breel-Donald Embolo2.392
Harry Kane2.332
Neymar da Silva Santos Junior2.132
Lautaro Javier Martínez2.120
Cristiano Ronaldo dos Santos Aveiro1.941
Enner Remberto Valencia Lastra1.923

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 use location and pass_end_location to 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 period to study how a team's pressing intensity changes as a match ages, and remember that period 5 is the shootout.
  • Pull the shot_freeze_frame column 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; the doc folder 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.