# Understat xG Football Scraper — Expected Goals & Shot Data API (`mirthful_radish/understat-xg-football-scraper`) Actor Extract xG, xA, and advanced football stats from Understat.com. 562+ players per league, 18 metrics including expected goals, npxG, xG chain. Covers Premier League, La Liga, Bundesliga, Serie A, Ligue 1, RFPL. Seasons from 2014/15. - **URL**: https://apify.com/mirthful\_radish/understat-xg-football-scraper.md - **Developed by:** [Sean Caldwell](https://apify.com/mirthful_radish) (community) - **Categories:** Other, Developer tools - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Understat xG Football Scraper Extract expected goals (xG), expected assists (xA), and advanced shot-level data from Understat.com — one of the last free sources of xG data for European football. Get structured JSON/CSV data for players, teams, and individual shots across 6 top leagues. ### What does this scraper do? This Actor extracts football analytics data from Understat.com and returns clean, structured data ready for analysis. Understat embeds data as JSON inside script tags rather than HTML tables, and this scraper handles the extraction and decoding automatically. **Use it for:** - Football analytics and scouting (xG, xA, shot maps) - Fantasy football research (FPL, Sorare) - Betting model data pipelines - Academic sports science research - Machine learning models on football data ### Features - **6 top leagues** — Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Russian Premier League - **Player-level xG data** — xG, xA, npxG, shots, key passes, goals, assists per player per season - **Team-level aggregates** — xG, xGA, results, points, wins/draws/losses - **Historical seasons** — data available from 2014/15 onwards - **Clean numeric output** — all stats properly parsed as numbers, not strings - **No Cloudflare issues** — Understat serves data without aggressive bot protection ### How to use 1. Select one or more **leagues** from the dropdown 2. Choose a **data type**: player stats or team stats 3. Set the **season** start year (e.g. "2024" for 2024/25) 4. Click **Start** and wait for results 5. Download as JSON, CSV, or Excel ### Output example Each result contains one player per row with all Understat metrics: ```json { "id": 1250, "player_name": "Mohamed Salah", "team_title": "Liverpool", "games": 29, "goals": 17, "assists": 11, "shots": 95, "key_passes": 48, "xG": 14.32, "xA": 7.85, "npg": 16, "npxG": 13.07, "xGChain": 19.45, "xGBuildup": 5.12, "league": "Premier League", "dataType": "league_players", "season": "2024" } ```` ### Supported leagues | League | Understat Code | Seasons Available | |---|---|---| | Premier League | EPL | 2014/15 — current | | La Liga | La\_Liga | 2014/15 — current | | Bundesliga | Bundesliga | 2014/15 — current | | Serie A | Serie\_A | 2014/15 — current | | Ligue 1 | Ligue\_1 | 2014/15 — current | | Russian Premier League | RFPL | 2014/15 — current | ### Data fields **Player stats** (league\_players): id, player\_name, team\_title, games, time, goals, assists, shots, key\_passes, xG, xA, npg, npxG, xGChain, xGBuildup, yellow\_cards, red\_cards, position. **Team stats** (league\_teams): id, title, matches, wins, draws, losses, scored, missed, xG, xGA, pts. ### Pricing This Actor uses pay-per-event pricing: | Event | Cost | Description | |-------|------|-------------| | Actor start | $0.10 | One-time per run | | League scraped | $0.49 | Per league of data returned | **Examples:** - Premier League players with xG: **$0.59** - All 6 European leagues: **$3.04** - Set a maximum cost limit before running to control spend ### Integrations Export data to Google Sheets, Excel, or connect via API. Works with n8n, Make.com, Zapier, and any tool that can call the Apify API. ### FAQ **Why Understat instead of FBref?** FBref is behind Cloudflare and requires expensive browser-based scraping. Understat serves data without aggressive bot protection, making it reliable and cost-effective. **Does this include xG data?** Yes. Every player record includes xG, xA, npxG, xGChain, and xGBuildup — the full Understat expected goals model. **Can I scrape historical seasons?** Yes. Understat has data from 2014/15 onwards. Enter the start year (e.g. "2014" for 2014/15). **What's the rate limit?** The Actor makes a maximum of 8 requests per minute and waits 6 seconds between requests to be respectful to Understat's servers. **Is this legal?** This Actor accesses only publicly available data on Understat.com. It respects rate limits and does not bypass authentication. Users are responsible for complying with applicable terms of service and laws. # Actor input Schema ## `leagues` (type: `array`): Leagues to scrape. Defaults to Premier League. ## `dataType` (type: `string`): Type of data to scrape. ## `season` (type: `string`): Season start year (e.g. 2024 for 2024/25). Leave empty for current season. ## `useProxy` (type: `boolean`): Enable proxy rotation. Usually not needed for Understat. ## `maxResults` (type: `integer`): Maximum number of rows to return. Leave empty for all. ## Actor input object example ```json { "leagues": [ "Premier League" ], "dataType": "league_players", "season": "2024", "useProxy": false } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "season": "2024" }; // Run the Actor and wait for it to finish const run = await client.actor("mirthful_radish/understat-xg-football-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "season": "2024" } # Run the Actor and wait for it to finish run = client.actor("mirthful_radish/understat-xg-football-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "season": "2024" }' | apify call mirthful_radish/understat-xg-football-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mirthful_radish/understat-xg-football-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Understat xG Football Scraper — Expected Goals & Shot Data API", "description": "Extract xG, xA, and advanced football stats from Understat.com. 562+ players per league, 18 metrics including expected goals, npxG, xG chain. Covers Premier League, La Liga, Bundesliga, Serie A, Ligue 1, RFPL. Seasons from 2014/15.", "version": "1.0", "x-build-id": "Unp4NeqceGBr3qdCc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mirthful_radish~understat-xg-football-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mirthful_radish-understat-xg-football-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mirthful_radish~understat-xg-football-scraper/runs": { "post": { "operationId": "runs-sync-mirthful_radish-understat-xg-football-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mirthful_radish~understat-xg-football-scraper/run-sync": { "post": { "operationId": "run-sync-mirthful_radish-understat-xg-football-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "leagues": { "title": "Leagues", "uniqueItems": true, "type": "array", "description": "Leagues to scrape. Defaults to Premier League.", "items": { "type": "string", "enum": [ "Premier League", "La Liga", "Bundesliga", "Serie A", "Ligue 1", "RFPL" ] }, "default": [ "Premier League" ] }, "dataType": { "title": "Data Type", "enum": [ "league_players", "league_teams" ], "type": "string", "description": "Type of data to scrape.", "default": "league_players" }, "season": { "title": "Season", "type": "string", "description": "Season start year (e.g. 2024 for 2024/25). Leave empty for current season." }, "useProxy": { "title": "Use Proxy", "type": "boolean", "description": "Enable proxy rotation. Usually not needed for Understat.", "default": false }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of rows to return. Leave empty for all." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```