Pricing

Rating

Developer

Actor stats

Categories

Share

Understat xG & Shot Data — Football Analytics

Scrapes understat.com: player and team season aggregates, per-match xG/PPDA/win-probabilities, shot-level data with x/y coordinates, situation/formation/game-state breakdowns, player career multi-season histories, and upcoming fixtures across the Big 5 European leagues + RFPL (2014/15 → 2025/26).

Why this actor

Most Understat scrapers stop at league-level aggregates. This one exposes every data tier Understat has, in a single run, with multi-season + multi-league support out of the box.

Pricing is pure pay-per-event. Per-row meters mean you pay for what you extract — no per-run fee, no per-league surcharge.

Modes

Pick a mode to determine what the actor scrapes:

⭐ match_shots is the killer feature — most scrapers don't expose it.

Pricing

No actor-start fee. No per-league surcharge. First 100 chargeable events of every run are free — enough to taste every tier including a 75-shot heatmap and a multi-season career bundle.

Cost cap

The maxCostUsd input (default $25) is a hard cap. The actor estimates cost up-front from your scope and warns you. Mid-run, every charge is checked against the cap; once hit, the run stops gracefully and writes a cost_cap_reached status row to the dataset.

Without this, a typo like all 6 leagues × all 11 seasons × match_shots could cost ~$375. With it, you're protected.

Sample inputs

Player season stats (parity workload)

{
"mode":"league_players",
"leagues":["EPL"],
"seasons":[2024]
}

Multi-season comparison (one run, not five)

{
"mode":"league_players",
"leagues":["EPL"],
"seasons":[2020,2021,2022,2023,2024]
}

Forwards-only with date range

{
"mode":"league_players",
"leagues":["La_liga"],
"seasons":[2024],
"positions":["F"],
"dateStart":"2024-08-01",
"dateEnd":"2024-12-31",
"minAppearances":5
}

Shot map for a single match

{
"mode":"match_shots",
"matchIds":[26630]
}

All shots in a season (heavy — uses your cost cap)

{
"mode":"match_shots",
"leagues":["EPL"],
"seasons":[2024],
"maxCostUsd":10
}

Mo Salah's complete career

{
"mode":"player_career",
"playerIds":[1250]
}

Arsenal's situation breakdowns

{
"mode":"team_situations",
"leagues":["EPL"],
"seasons":[2024],
"teams":["Arsenal"]
}

Upcoming Premier League fixtures

{
"mode":"fixtures",
"leagues":["EPL"],
"seasons":[2025]
}

Output

Every row carries:

• type — discriminator (player_season, team_season, match, shot, team_situation, player_career_season, fixture, or status)
• _meta.mode — which mode produced the row
• _meta.scrapedAt — ISO 8601 timestamp
• _meta.source — always "understat"

Set includeRawJson: true to attach the original Understat record under _raw (useful for power users; off by default to keep the dataset light).

Resume

Long runs check-point progress to a named key-value store keyed by mode + input scope. If a run is interrupted, the next run with the same input picks up where it left off — already-completed (league × season) or (matchId) or (playerId) units are skipped.

Limits

• leagues × seasons ≤ 60 — protects against accidental over-scope (e.g. 6 × 11 = 66 league-seasons).
• Cost cap defaults to $25/run.
• match_shots throttles requests to 6 s between matches to mirror the empirically safe rate. Expect a full EPL season (~380 matches × ~25 shots) to take ~40 minutes.
• RFPL team names are Cyrillic — the actor URL-encodes them automatically.
• Future fixtures have null xG fields until played.

Coverage

Notes

• This actor scrapes a publicly accessible website. Be mindful of Understat's resources — the built-in throttle is conservative, and match_shots adds an extra delay because of its high fan-out.
• The xG values are Understat's neural-net model output. If you need the underlying training data or the model itself, you'll need to talk to them.
• Data freshness lags Understat's updates by minutes-to-hours depending on their crawl cadence.