Understat Football Data Python

Run the hosted Understat xG Scraper on Apify without writing code, or integrate it with Python, JavaScript or cURL to collect normalized football expected-goals data.

This public repository contains working API examples, a complete sample input, six representative output rows and a CSV fixture. It documents the integration surface without publishing the Actor source code or private runtime configuration. The Actor is unofficial and is not affiliated with Understat.

Open Understat xG Scraper on Apify

What this repository helps you do

• Collect league tables, player summaries and fixtures for six supported domestic leagues.
• Analyze teams, players and matches with xG, xA, xPoints, PPDA, shots and roster data.
• Find an Understat player ID from a name before requesting a player report.
• Build shot maps, dashboards, notebooks or repeatable football-data pipelines.
• Export normalized Dataset rows as JSON, JSONL, CSV, Excel, XML or RSS.

Example result

data/sample-output.json contains one representative row from each of the six report modes. data/sample-output.csv provides a tabular subset.

{
  "recordType": "league_team",
  "league": "EPL",
  "season": 2024,
  "teamName": "Aston Villa",
  "matches": 38,
  "points": 66,
  "goalsFor": 58,
  "goalsAgainst": 51,
  "xG": 66.385246,
  "xGA": 54.998103,
  "xPoints": 61.5269,
  "ppda": 12.388811
}

Run without code

You can collect Understat football data directly from the Apify web interface:

1. Open Understat xG Scraper on Apify.
2. In the Input tab, choose one report in What report do you want?.
3. Complete only the league, season or target needed by that report. Leaving Target empty uses a working example.
4. Keep Maximum rows to save and charge at 1 for a minimal first test, then click Start.
5. Open the Dataset tab to inspect the normalized rows and select the most useful table view.
6. Export the Dataset in your preferred format.

See docs/no-code-guide.md for a mode-by-mode walkthrough and data/sample-input.json for the exact prefilled input.

Try it with Apify's free plan

Apify's Free plan includes $5 in monthly prepaid usage for the Apify Store or your own Actors, with no credit card required to start. This can cover a small Understat xG Scraper test while credit is available; it is not unlimited free usage.

Unused credit expires at the end of the billing cycle. Check the current Apify pricing before running a larger export.

Quick start for developers

Python

1. Install the client

pip install -r examples/python/requirements.txt

2. Set your Apify token

export APIFY_API_TOKEN="your-token"

On Windows PowerShell:

$env:APIFY_API_TOKEN = "your-token"

3. Run the example

python examples/python/understat_football_data.py

The script reads data/sample-input.json, calls the hosted Actor and prints each returned Dataset row as JSON.

Input example

{
  "mode": "league",
  "league": "EPL",
  "season": 2024,
  "target": "",
  "maxItems": 1,
  "includePlayers": true,
  "includeMatches": true,
  "includeShots": true,
  "includeBreakdowns": true,
  "includeRosters": true
}

The payload mirrors every visible field in the current Apify prefill. See docs/input-reference.md for the valid modes, accepted target values and option behavior.

Request examples

cURL

Use examples/curl-request.md for a synchronous request that returns Dataset items.

Python

• understat_football_data.py runs the sample input.
• search_player_id.py finds player IDs by name.
• export_understat_csv.py converts a JSON Dataset export to CSV.

JavaScript

Use examples/javascript/request.mjs with the official Apify JavaScript client.

All request examples call the hosted Actor. They do not contain a token, proxy setting, private endpoint or Actor source code.

Output fields

Every row has these three provenance fields:

Field	Meaning
recordType	Identifies the row shape, such as league_team, player_shot or match_roster.
sourceUrl	Public Understat page used for the record.
fetchedAt	UTC timestamp for the source response.

The six modes can produce thirteen record types: league_team, league_player, league_match, team_player, team_match, team_breakdown, player_profile, player_match, player_shot, match_roster, match_shot, player_search_result and global_trend.

Common metrics include goals, xG, xGA, xA, xPoints, shots, ppda, match score and forecasts, shot coordinates and context, player minutes and cards, and monthly home/away goal and xG averages. Read docs/output-reference.md for the field groups and nullable behavior.

Common use cases

docs/use-cases.md contains complete input examples for:

• League and team benchmarking.
• Player analysis and shot-map datasets.
• Match rosters and shot events.
• Player ID discovery.
• Monthly xG trend analysis.

How to get Understat data with Python

Run examples/python/understat_football_data.py with APIFY_API_TOKEN set. Change the object in data/sample-input.json to select a mode, then iterate the default Dataset returned by the official Apify client.

For a player whose numeric ID is unknown, run examples/python/search_player_id.py first and use the returned playerId as the target of a player report.

How to export Understat xG data to CSV

Download the default Dataset as CSV from Apify Console, or export a JSON Dataset file locally:

python examples/python/export_understat_csv.py data/sample-output.json data/exported-understat-data.csv

The exporter builds a stable header from the union of top-level fields and leaves unavailable values blank instead of converting them to zero or false.

Understat shots, rosters and expected-goals data

Use mode: "player" or mode: "match" with includeShots: true for shot rows. A player_shot or match_shot row can include minute, x, y, xG, result, situation, shotType, assistedBy and lastAction.

Use mode: "match" with includeRosters: true for match_roster rows containing positions, minutes, goals, assists, cards, xG, xA, xGChain and xGBuildup.

FAQ

See docs/faq.md for answers about supported leagues, season notation, player IDs, row selection, exports, billing and empty results.

Limits and pricing

• One run processes one report mode and one league, team, player or match where applicable.
• Supported leagues are EPL, La Liga, Bundesliga, Serie A, Ligue 1 and the Russian Premier League.
• maxItems accepts 1 to 5,000 and limits both saved and billed rows.
• Each successfully delivered Dataset row creates exactly one event for the selected mode.
• There is no Actor-start event or fixed per-run fee.
• Empty results, failures and rows excluded by maxItems are not billed as row events.

Current tier prices are $1 per 1,000 rows on Free, $0.90 on Bronze, $0.80 on Silver, and $0.75 on Gold, Platinum or Diamond. The exact charge is proportional to delivered rows and is not rounded to blocks of 1,000. The Actor Pricing tab is authoritative for current rates and spending controls.

Source coverage varies by competition, season and entity. A valid accepted input can return no rows when Understat does not provide matching data.

Hosted version

Use the hosted Actor for its guided input, managed execution, Dataset storage, table views, schedules, Tasks and API access without maintaining scraping infrastructure:

Run Understat xG Scraper on Apify

Responsible use

Use the returned public data lawfully and respect the source's terms, applicable laws, privacy obligations and third-party rights. This project is unofficial and is not affiliated with Understat. Never commit an Apify token or other credential to this repository.

Support

For an example or documentation problem, open a GitHub issue with the command, sanitized input and error message. For an execution problem, include the Apify run ID but never include your token.

License

This repository is released under the MIT License.