# Understat xG Scraper – Football Data & Analytics (`datascraperes/understat-football-data`) Actor

Scrape normalized Understat xG data for leagues, teams, players and matches, including shots, rosters, xA, PPDA and global trends. Export JSON, CSV or Excel. Pay $0.75-$1 per 1,000 delivered rows based on your Apify plan.

- **URL**: https://apify.com/datascraperes/understat-football-data.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.75 / 1,000 league rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

Scrape normalized Understat expected goals (xG) data for leagues, teams, players, and matches, including shots, rosters, xA, PPDA, and global football trends. This Understat xG scraper returns analysis-ready football analytics for JSON, CSV, Excel, dashboards, or API workflows for $0.75–$1.00 per 1,000 delivered rows, depending on your Apify plan, with no start fee.

This Actor is unofficial and is not affiliated with Understat.

### What this Actor does

The Actor offers six focused modes:

- **League overview** returns team-season summaries, player-season summaries, and fixtures/results.
- **Team overview** returns player summaries, matches, and tactical/statistical breakdowns.
- **Player overview** returns one player profile plus match-by-match and shot-by-shot records.
- **Match details** returns roster appearances and individual shots.
- **Find a player ID** searches by name so you can run Player overview without manually browsing for an ID.
- **Global monthly trends** returns monthly home/away goals and xG averages by league.

Every row includes a `recordType`, `sourceUrl`, and UTC `fetchedAt` timestamp. Numeric source values are converted to JSON numbers, while stable identifiers remain strings so they are safe to export and join.

### Use cases

- Build football analytics dashboards with goals, xG, xA, xPoints, PPDA, shots, and results.
- Compare teams or players across seasons in spreadsheets, databases, or BI tools.
- Create shot maps and player-performance timelines from event-level rows.
- Monitor fixtures and completed matches for the supported domestic leagues.
- Enrich match analysis with rosters, positions, minutes, cards, and buildup metrics.

### How to use

1. Open the Actor in Apify Console.
2. Select **What report do you want?**. Each option states the record groups it returns.
3. For League, choose a league and season. For Team, Player, Match, or player search, enter the name, ID, or URL in the single **Target** field. Leave Target empty to run a working example for the selected report.
4. Keep the optional section closed for the recommended complete export, or open **Choose included data** to remove record groups you do not need.
5. Click **Start** and open the Dataset when the run finishes.

### Input

The form keeps only five fields in the main section. Every field has an explanatory tooltip, and fields that do not apply to the selected report are safely ignored.

| Main field | Used by | Default / form prefill | Description |
|---|---|---:|---|
| `mode` | All runs | `league` / `league` | Selects one of six clearly labelled reports. |
| `league` | League | `EPL` / `EPL` | Selects `EPL`, `La_liga`, `Bundesliga`, `Serie_A`, `Ligue_1`, or `RFPL`. Other reports ignore it. |
| `season` | League, Team | `2024` / `2024` | Season start year; `2024` means 2024/25. A year in a Team URL takes precedence. |
| `target` | Team, Player, Match, player search | Empty / empty | Accepts a team name/URL, player ID/URL, match ID/URL, or player name according to `mode`. Empty uses a working example. |
| `maxItems` | All runs | `1000` / `1` | Maximum rows saved and billed. The form starts with a one-row sample costing at most USD 0.001; an API call that omits the field uses the 1,000-row default. Increase it up to 5,000 when needed. |

The collapsed **Choose included data** section contains `includePlayers`, `includeMatches`, `includeShots`, `includeBreakdowns`, and `includeRosters`. All default to `true`; each tooltip states exactly which reports it affects and which rows it adds. They are shown explicitly in the prefilled input so the generated API examples expose every current user option. Network fallback, timeout, and retry behavior are managed automatically, so users do not need to configure transport settings.

This is the exact prefilled input. It produced the League result example below:

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

### Output

Results are stored in the run's default Dataset. Depending on the selected mode, `recordType` is one of `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`, or `global_trend`.

Apify Console also provides purpose-built table views for complete league reports, league tables, shots, tactical breakdowns, player analysis, match rosters, player ID searches, and monthly global trends. Select the view that matches your report to see its most useful fields first; downloads and API access still use the same normalized Dataset rows.

The separate `SUMMARY` output reports the selected mode, saved and available row counts, record counts by type, request attempts, transport used, truncation state, warnings, and a `billing` block. That block identifies the event name and shows requested, delivered, and charged rows. A valid source response with no matching records finishes with an empty Dataset and zero row events. A missing entity, access denial, challenge page, or incompatible response fails visibly instead of being saved as successful data.

Each selected mode uses one billing event, and every row saved by that mode creates one event. A mode can return several `recordType` values; the examples below show one complete, real row for every billing event.

| Selected mode | Billing event | Example record type |
|---|---|---|
| League overview | `league-result` | `league_team` |
| Team overview | `team-result` | `team_player` |
| Player overview | `player-result` | `player_profile` |
| Match details | `match-result` | `match_roster` |
| Find a player ID | `player-search-result` | `player_search_result` |
| Global monthly trends | `global-trend-result` | `global_trend` |

#### League result example

```json
{
  "recordType": "league_team",
  "sourceUrl": "https://understat.com/league/EPL/2024",
  "fetchedAt": "2026-09-03T11:26:51.771396Z",
  "league": "EPL",
  "season": 2024,
  "teamId": "71",
  "teamName": "Aston Villa",
  "matches": 38,
  "wins": 19,
  "draws": 9,
  "losses": 10,
  "points": 66,
  "goalsFor": 58,
  "goalsAgainst": 51,
  "xG": 66.385246,
  "xGA": 54.998103,
  "nonPenaltyXG": 61.710806,
  "nonPenaltyXGA": 52.714603,
  "xPoints": 61.5269,
  "deepCompletions": 285,
  "deepAllowed": 248,
  "ppda": 12.388811,
  "ppdaAllowed": 9.955724
}
```

#### Team result example

```json
{
  "recordType": "team_player",
  "sourceUrl": "https://understat.com/team/Arsenal/2024",
  "fetchedAt": "2026-09-03T10:09:13.688569Z",
  "league": null,
  "season": 2024,
  "playerId": "5220",
  "playerName": "Kai Havertz",
  "teamName": "Arsenal",
  "position": "F M S",
  "appearances": 23,
  "minutes": 1880,
  "goals": 9,
  "nonPenaltyGoals": 9,
  "assists": 3,
  "shots": 53,
  "keyPasses": 17,
  "yellowCards": 5,
  "redCards": 0,
  "xG": 11.830620590597391,
  "nonPenaltyXG": 11.830620590597391,
  "xA": 2.9488715566694736,
  "xGChain": 16.01736629009247,
  "xGBuildup": 4.696250442415476
}
```

#### Player result example

```json
{
  "recordType": "player_profile",
  "sourceUrl": "https://understat.com/player/7322",
  "fetchedAt": "2026-09-03T10:09:25.201582Z",
  "playerId": "7322",
  "playerName": "Bukayo Saka",
  "favoritePosition": "FWR",
  "league": "EPL",
  "teamName": "Arsenal",
  "season": 2026,
  "matchCount": 228,
  "shotCount": 511
}
```

#### Match result example

```json
{
  "recordType": "match_roster",
  "sourceUrl": "https://understat.com/match/26602",
  "fetchedAt": "2026-09-03T10:09:34.659174Z",
  "matchId": "26602",
  "side": "h",
  "rosterId": "666169",
  "playerId": "10913",
  "teamId": "89",
  "playerName": "André Onana",
  "position": "GK",
  "minutes": 90,
  "goals": 0,
  "ownGoals": 0,
  "shots": 0,
  "xG": 0,
  "keyPasses": 0,
  "assists": 0,
  "xA": 0,
  "yellowCards": 0,
  "redCards": 0,
  "subbedIn": 0,
  "subbedOut": 0,
  "xGChain": 0.14530973136425018,
  "xGBuildup": 0.14530973136425018
}
```

#### Player search result example

```json
{
  "recordType": "player_search_result",
  "sourceUrl": "https://understat.com/",
  "fetchedAt": "2026-09-03T10:09:45.350435Z",
  "query": "Saka",
  "playerId": "7322",
  "playerName": "Bukayo Saka",
  "teamName": "Arsenal"
}
```

#### Global trend result example

```json
{
  "recordType": "global_trend",
  "sourceUrl": "https://understat.com/",
  "fetchedAt": "2026-09-03T10:09:55.484108Z",
  "league": "RFPL",
  "leagueId": "6",
  "year": 2014,
  "month": 8,
  "matches": 48,
  "homeGoalsPerMatch": 1.4583,
  "awayGoalsPerMatch": 1.125,
  "homeXGPerMatch": 1.4501787355790536,
  "awayXGPerMatch": 1.0161208802989374
}
```

You can download Dataset results in JSON, JSONL, CSV, Excel, XML, or RSS formats available in Apify Console.

### Pricing

The Actor uses pay-per-event billing. One event always means one successfully delivered Dataset row, regardless of its `recordType` or selected mode. Apify automatically applies the rate for your plan:

| Apify pricing tier | Price per delivered row | Equivalent per 1,000 delivered rows |
|---|---:|---:|
| Free | $0.001 | $1.00 |
| Bronze | $0.0009 | $0.90 |
| Silver | $0.0008 | $0.80 |
| Gold | $0.00075 | $0.75 |
| Platinum | $0.00075 | $0.75 |
| Diamond | $0.00075 | $0.75 |

All six modes use this same tier table; only the event name changes as shown in the Output section. Tiers are based on your Apify plan, not on the number of rows in one run. The actual charge remains proportional to the exact number of rows delivered and is not rounded to 1,000-row blocks. For example, 250 rows cost $0.25 on Free, $0.225 on Bronze, $0.20 on Silver, or $0.1875 on Gold, Platinum, and Diamond.

There is no Actor-start event, no fixed per-run fee, and no second automatic Dataset-item event. Empty results, failed requests, discarded records, and rows omitted because of `maxItems` or the run's maximum charge do not create a row event. Set a maximum total charge in Apify before a large run; if that limit is reached, the Actor saves and charges only the affordable prefix and reports the truncation in `SUMMARY`.

The Actor's **Pricing** tab is the authoritative source for the active rate and spending controls.

### Related Actors

| Actor | Best for |
|---|---|
| [Similarweb Website Traffic & SEO Analytics Scraper](https://apify.com/datascraperes/similarweb-website-scraper) | Adding website audience, ranking, and competitor intelligence when club or league research also covers digital reach. |

### Limits and data quality

- League coverage is limited to the six leagues listed in the input. Source availability varies by competition and season.
- Season inputs start at 2014, but an accepted year can still return no records when the source has no data for it.
- One mode and one entity are processed per run. The complete response is normalized, then `maxItems` is applied in deterministic order.
- The Actor uses 256 MB of memory and bounded network attempts to keep the platform cost represented by the row price under control.
- League mode always includes team summaries. Team mode needs at least one of players, matches, or breakdowns enabled; Match mode needs rosters or shots enabled.
- Source timestamps do not include an explicit timezone. Treat `dateTime` as the source's displayed match time rather than assuming UTC.
- Understat values and forecasts can change when the source corrects or refreshes data. Use `fetchedAt` to identify your collection time.
- The source interfaces used by public pages are not documented as a stable public API and may change without notice. Contract changes are reported as errors instead of silently producing malformed rows.
- Direct access is attempted first. An owner-managed fallback is applied automatically only after transient connection or 5xx failures. Explicit access denials, rate limits, or challenge pages are not bypassed.
- A failed source request cannot produce partial rows because each mode uses one bounded source response. `maxItems` and maximum-charge truncation are clearly marked in `SUMMARY`; only the rows actually saved are billed.

### Frequently asked questions

#### How do I find a player ID?

Select **Find a player ID**, enter part of the player's name, and run the Actor. Copy `playerId` from the matching Dataset row into a new Player overview run.

#### Do I need a proxy?

No. Network handling is automatic: the Actor tries the efficient direct route first and has an owner-managed fallback for temporary connection or server failures. There is no proxy input to configure.

#### Which year should I enter for a season?

Enter the year in which the season started. For example, use `2024` for 2024/25.

#### Why did I receive fewer rows than expected?

Open `SUMMARY` and check `truncated`, `totalRecords`, `savedRecords`, and `warnings`. Increase `maxItems` up to 5,000 or disable record groups you do not need.

#### Is this an official Understat integration?

No. This Actor is an independent tool and is not endorsed by or affiliated with Understat.

### Responsible use

Use this Actor only for lawful collection of public football data and only when you have the right to automate access. Understat's published robots policy observed during development disallows automated crawling, so review the current policy and terms before every production use and obtain permission where required. Do not use proxies or retries to bypass access controls, rate limits, challenge pages, or other technical restrictions. You are responsible for compliance with applicable laws, contractual terms, database rights, privacy rules, and third-party rights.

### Support

If a run fails or returns unexpected data, open an issue in the Actor's **Issues** tab and include the run ID, selected mode, non-sensitive input, expected behavior, and observed behavior. Do not post proxy URLs, credentials, API tokens, or other secrets.

[Understat football data Python guide, API examples, and sample dataset](https://github.com/datacrawler-edu/understat-football-data-python)

# Actor input Schema

## `mode` (type: `string`):

Choose one report per run. League returns teams, players, and matches; Team returns players, matches, and breakdowns; Player returns a profile, matches, and shots; Match returns rosters and shots; Find a player ID searches by name; Global trends returns monthly league averages. Each saved row is billed once at the rate for your Apify plan.

## `league` (type: `string`):

Used only for League. Select one of the six competitions available from Understat. It is ignored by Team, Player, Match, player search, and Global trends reports.

## `season` (type: `integer`):

Used only for League and Team reports. Enter the year in which the season started: 2024 means 2024/25. Years from 2014 to 2100 are accepted, but the source may not contain every competition and season. A year included in a Team URL overrides this value.

## `target` (type: `string`):

Leave empty to try a working example. For Team enter a name, slug, or Understat team URL (example: Arsenal). For Player enter its numeric ID or player URL (example: 7322). For Match enter its numeric ID or match URL (example: 26602). For Find a player ID enter at least two characters of the player's name (example: Saka). League and Global trends ignore this field.

## `maxItems` (type: `integer`):

Safety limit for the entire run, from 1 to 5,000. The form starts at 1 for a test costing at most USD 0.001; if an API call omits this field, the 1,000-row default costs at most USD 1.00 and less on eligible paid Apify plans. Increase it when you need more data. Only successfully saved rows are billed.

## `includePlayers` (type: `boolean`):

League and Team only. When enabled, saves one aggregate row per player. It has no effect on Player, Match, player search, or Global trends reports.

## `includeMatches` (type: `boolean`):

League and Team: includes fixtures and completed matches. Player: includes match-by-match performance. It has no effect on Match, player search, or Global trends reports.

## `includeShots` (type: `boolean`):

Player and Match only. Saves one row per shot with coordinates, xG, situation, result, body part, and assist context. Shot rows can be the largest part of a result.

## `includeBreakdowns` (type: `boolean`):

Team only. Includes aggregate rows by situation, formation, game state, timing, shot zone, attack speed, and result.

## `includeRosters` (type: `boolean`):

Match only. Saves one row per player appearance, including team, position, minutes, goals, cards, xG, xA, xGChain, and xGBuildup.

## `team` (type: `string`):

Backward-compatible API field. New runs should use target.

## `playerId` (type: `integer`):

Backward-compatible API field. New runs should use target.

## `matchId` (type: `integer`):

Backward-compatible API field. New runs should use target.

## `searchQuery` (type: `string`):

Backward-compatible API field. New runs should use target.

## Actor input object example

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

# Actor output Schema

## `results` (type: `string`):

Normalized records selected by the run mode.

## `summary` (type: `string`):

Counts, truncation state, billing event and charged-row total, request transport, and warnings for the run.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "league",
    "league": "EPL",
    "season": 2024,
    "target": "",
    "maxItems": 1,
    "includePlayers": true,
    "includeMatches": true,
    "includeShots": true,
    "includeBreakdowns": true,
    "includeRosters": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/understat-football-data").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "league",
    "league": "EPL",
    "season": 2024,
    "target": "",
    "maxItems": 1,
    "includePlayers": True,
    "includeMatches": True,
    "includeShots": True,
    "includeBreakdowns": True,
    "includeRosters": True,
}

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/understat-football-data").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "league",
  "league": "EPL",
  "season": 2024,
  "target": "",
  "maxItems": 1,
  "includePlayers": true,
  "includeMatches": true,
  "includeShots": true,
  "includeBreakdowns": true,
  "includeRosters": true
}' |
apify call datascraperes/understat-football-data --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datascraperes/understat-football-data"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QflHrq7kWd6yUPEGi/builds/ZHA1nGjEAg03tJJiM/openapi.json