The Short Answer

The fastest route into Python is a CSV and pandas: download a free sample, read it with read_csv, and you are modelling in minutes. When the work graduates from samples to a full dataset, the same columns come from the Dribble API through a small Python client, or from BigQuery tables you query directly. This guide walks the whole route, from first file to first model output.

How Do I Start With Free Football Data in Python?

Dribble publishes free sample data on Kaggle: 18 current-season sample CSVs covering players, teams, matches, and match events. No account with Dribble is needed, and the files carry the same schema as the paid data, so code you write against the samples keeps working when you scale up.

import pandas as pd

events = pd.read_csv("match_events.csv")
print(events.shape)
print(events.columns.tolist())

The event file is the one modellers live in. Each row is one on-ball event: a shot, a pass, a carry, a pressure, with pitch coordinates and qualifiers. Across the full dataset that is more than 57 million event rows, covering 32 competitions from 2020 to the present.

How Do I Load and Explore the Sample Data?

Start by learning the shape of the data before you model anything:

shots = events[events["event_type"] == "Shot"].copy()
print(shots["competition"].value_counts().head())
print(shots[["player", "x", "y", "expected_goals"]].head(10))

Three habits save days later. First, check coverage per competition and season before pooling rows; not every league carries every metric. Second, treat nulls as information: in count fields a null usually means zero where the metric is covered, while a null in expected goals means no qualifying action was recorded. Third, keep the season label with every extract, because player and team match files are season-scoped and a season parameter is required when you query them.

The core tables are sized for real work: 90,582 players, 8,054 teams, 41,017 matches, and around 210,000 player-match rows per season.

How Do I Query the Live API From Python?

Samples are for learning. Live work uses the API, and there is a Python client so you never hand-roll pagination or headers:

pip install "dribble[pandas]"

import os
from dribble import Client

client = Client(api_key=os.environ["DRIBBLE360_API_KEY"])
matches = client.matches(season="2025/2026")
team_matches = client.fetch_df("team_matches", season="2025/2026")
player_matches = client.fetch_df("player_matches", season="2025/2026")

You generate a key at dribble360.com/api-subscribers; it is shown once, so store it in an environment variable. Calls are paginated automatically by the client, rate limits reset at midnight UTC, and the API tiers run from Lite at $19 a month (1,000 calls a day) to Flite at $149 a month (50,000 calls a day).

How Do I Turn It Into a Model Output?

Here is a complete, small model: attack ratings from team expected goals, the same input most public xG models start from.

attack = (
    team_matches.groupby("team", as_index=False)
    .agg(matches=("match_id", "nunique"), xg=("expected_goals", "mean"))
    .sort_values("xg", ascending=False)
)
attack["xg_vs_average"] = attack["xg"] - attack["xg"].mean()
print(attack.head(10))

That table is a ranking of team attacking output per match, adjusted against the league average, in about ten lines. From here the standard steps are all pandas: merge player_matches for player-level expected goals and expected assists, join matches for dates and opponents, and fit a regression or a Poisson goals model on the per-team rows. Because the sample CSVs and the API share a schema, this exact code runs on the free samples first, which is how you validate a pipeline before paying for the full history.

If your data volumes outgrow files and API pages, the same datasets sit in BigQuery (Starter $49, Pro $149, Max $499 a month), where one SQL query replaces a folder of CSVs.

What Should I Watch Out For?

Licences decide what you may ship. Personal and research use is permitted on every paid plan, and the free samples are for learning and evaluation. Commercial products, apps, dashboards, and models you sell need a commercial tier: API Elite or Flite, or BigQuery Pro or Max. Raw data redistribution is never included without a signed addendum, on any tier.

Also mind the mechanics: player-match and team-match queries require a season parameter, API keys expire by plan and only work while the subscription is active, and daily call allowances are shared across all keys on an account.

Ready to run it on the full dataset? See plans and pricing, or start from our background guide to football data for analytics.