Understat xG & Shot Data - Football Analytics
constructive_calm--understat-football-analyticsScrape Understat football data for xG, shots, PPDA, player and team season stats, career histories, and fixtures across Big 5 leagues and RFPL. Use it to build match and betting analytics datasets.
Instructions
Understat xG & Shot Data - Football Analytics. Scrapes Understat: player/team season aggregates, per-match xG/PPDA/win-probabilities, shot-level data with x/y coords + xG, situation/formation/game-state breakdowns, player career histories, and fixtures across the Big 5 + RFPL (2014–2025). Multi-season + multi-league in a single run.
When to use: Use for expected goals (xG), shot maps, PPDA and player or team season stats in the Big 5 European leagues and RFPL.
Returns: the run's dataset rows as structured JSON (one row per result), plus the run and dataset IDs for paging the full dataset.
Behavior: starts one run of the Apify Actor "constructive_calm/understat-football-analytics" through Apify's hosted MCP gateway (mcp.apify.com) with your own APIFY_TOKEN; the run uses your Apify account. Read-only: it only reads public web data and changes nothing on the source site. Docs: https://apify.com/constructive_calm/understat-football-analytics
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"mode": "<mode>"
},
"name": "constructive_calm--understat-football-analytics"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | What to scrape. 'league_players' returns per-player season aggregates (xG, xA, xGChain, xGBuildup, etc). 'league_teams' returns team season aggregates (W/D/L, xG, xGA, PPDA, points, xPoints). 'league_matches' returns played-match metadata (xG, win-prob, deep, ppda). 'match_shots' returns every shot with x/y coords, xG, situation, body part, result. 'team_situations' returns long-format breakdowns by situation/formation/game-state/timing/zones. 'player_career' returns one player's full multi-sea… | league_players |
| teams | No | Filter output to specific teams. Applies to league_players, league_teams, league_matches, fixtures, match_shots (league discovery) and team_situations. Names must match Understat's display names — e.g. 'Arsenal', 'Manchester United', 'Real Madrid' (matching is case-insensitive). A name that matches nothing produces a 'team_not_matched' status row with closest-name suggestions instead of failing silently. | |
| dateEnd | No | Restrict league_players stats to matches on or before this date. Leave empty for none. | |
| leagues | No | One or more of the six leagues Understat covers. Required for league_*, match_shots (when matchIds is empty), team_situations (when teams is empty), and fixtures. | |
| seasons | No | List of season start years as integers — 2025 = the 2025/26 season. Understat history goes back to 2014. The current season becomes valid automatically once it kicks off in August. Invalid entries are reported in a status row instead of being dropped silently. | |
| matchIds | No | Specific match IDs to scrape directly (used by match_shots). When set, leagues/seasons are ignored. Find IDs in Understat URLs: /match/{ID}. | |
| dateStart | No | Restrict league_players stats to matches on or after this date. Leave empty for none. | |
| playerIds | No | Player IDs for player_career mode. Find IDs in Understat URLs: /player/{ID}. Examples: 553 (Messi), 619 (Agüero), 1250 (Salah), 8260 (Haaland). | |
| positions | No | Filter players by position. Only applies to league_players mode (uses Understat's filtered POST endpoint). | |
| maxCostUsd | No | Hard cap on the run's total billed amount. The actor estimates cost up-front and stops gracefully if the cap is hit mid-run. | |
| maxResults | No | Stop emitting after this many dataset rows. 0 = unlimited (subject to maxCostUsd). | |
| nLastMatches | No | Filter player stats to the last N matches. 0 = full season. Only applies to league_players mode. | |
| includeRawJson | No | When true, attach the original Understat record under `_raw` on every output row. Useful for power users / debugging. Default off — keeps the dataset light. | |
| minAppearances | No | Drop player rows where games played is below this threshold (client-side filter). 0 = no filter. | |
| proxyConfiguration | No | Apify proxy. Understat does not block scrapers, but residential proxies help users behind corporate networks. Default = Apify residential. |