Understat API

Expected goals data from Understat as JSON: league tables, fixtures, shot maps, players and teams.

The API.SH Understat API returns Understat's expected goals data as JSON for the Premier League, La Liga, Bundesliga, Serie A, Ligue 1 and the Russian Premier League. Get xG league tables with xPTS and PPDA, every fixture with xG and win probabilities, every shot of a match with pitch coordinates, and season and career stats for players and teams.

Get a free API key Try it in the playground

6 endpoints
from $1 / 1,000 calls
1,000 free credits / month
failed calls free

xG league table

GET https://api.api.sh/understat/v1/league

{ "success": true }

1 credit · $1 per 1,000 calls

What you can build with the Understat API

xG league tables and over-performance

Pull a season's table with xG, xGA, npxG, expected points and pressing (PPDA) to see which teams are riding luck and which are underrated.

/league

Shot maps and match analysis

Get every shot of a match with minute, player, situation, shot type, x/y position and xG, plus both line-ups with xG, xA, xGChain and xGBuildup.

/match /league-matches

Player scouting and fantasy football

Rank every player in a league by xG, npxG, xA, key passes or minutes, filter by team or position, then open a player's full career split by season and situation.

/league-players /player

Betting and prediction models

Use each fixture's xG and home, draw and away win probabilities, finished or upcoming, as features for your own match models.

/league-matches /team

Team tactical profiles

Read a team's season shot statistics for and against by situation, formation, game state, timing, shot zone and attack speed.

/team

Understat data you get

Field names from real responses. Numbers come parsed, URLs absolute, dates in ISO 8601.

Understat API endpoints and prices

Every Understat endpoint costs 1 credit per call: credits are $1 per 1,000 on a monthly plan, $2 pay-as-you-go. Pricing

Products, listings and places1

Player xG career

/understat/v1/player

$1 · $2 PAYG

1 credit

More data5

xG league table /understat/v1/league	$1 · $2 PAYG 1 credit
Fixtures and results with xG and win probabilities /understat/v1/league-matches	$1 · $2 PAYG 1 credit
xG stats of every player in a league season /understat/v1/league-players	$1 · $2 PAYG 1 credit
Match shots with xG and line-ups /understat/v1/match	$1 · $2 PAYG 1 credit
Team season with xG /understat/v1/team	$1 · $2 PAYG 1 credit

Call the Understat API

xG league table: GET https://api.api.sh/understat/v1/league

curl "https://api.api.sh/understat/v1/league?league=EPL" \
  -H "x-api-key: $APISH_KEY"

import os, requests

res = requests.get(
    "https://api.api.sh/understat/v1/league",
    params={"league": "EPL"},
    headers={"x-api-key": os.environ["APISH_KEY"]},
    timeout=120,
)
res.raise_for_status()
data = res.json()

const url = new URL("https://api.api.sh/understat/v1/league");
url.searchParams.set("league", "EPL");

const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

# Google Sheets (API.SH add-on)
=APISH("/understat/v1/league", "league", "EPL")

# Zapier, Make, n8n (verified node): pick the API.SH app,
# choose "Understat" and "xG league table".

# AI agents (Claude, ChatGPT, Cursor): add the
# API.SH MCP server https://api.sh/mcp

Create a free accountConfirm your email and get 1,000 free credits every month. No card needed.
Create an API keyOne key works for all 483 platforms.
Send the requestJSON back in one call. Add output=csv or output=ndjson for files.

Why API.SH for Understat data

Public data only: no Understat login, cookies or account needed
One key and one response shape for Understat and 482 other platforms
Built and maintained by API.SH, not third-party publishers
Pay per call; errors on our side cost nothing
Live status for every endpoint

API.SH vs the official Understat API

Understat does not publish an official API; the community packages that rank for it (understat and understatapi on PyPI, worldfootballR) read the website directly and break when the site changes. API.SH maintains the data access for you and returns the same xG data as stable JSON.

A maintained alternative to the understat Python packages, Kaggle notebooks with Beautiful Soup, or an Apify actor: one key, a fixed price per call, and blocks and retries are handled for you.

Understat API questions

What Understat data can I get?+

xG league tables (/understat/v1/league), fixtures and results with xG and win probabilities (/understat/v1/league-matches), every player's season stats (/understat/v1/league-players), a match's shots and line-ups (/understat/v1/match), a player's career with every shot (/understat/v1/player) and a team's season (/understat/v1/team).

How much does the Understat API cost?+

Every Understat endpoint costs 1 credit per call. On a monthly plan 1,000 credits cost $1 (Starter is $50/month for 50,000 credits). Pay-as-you-go is $2 per 1,000 credits, with top-ups from $15 that never expire.

Is there a free trial?+

Yes. Every account gets 1,000 free credits every month. That is 1,000 calls to /understat/v1/league at 1 credit each.

Is there an official Understat API?+

No. Understat has no public developer API. The Python libraries you find on GitHub and PyPI read the site's pages, so they need fixing when the site changes. API.SH keeps the endpoints working and returns consistent JSON.

Do I need an Understat account or login?+

No. API.SH reads public Understat pages only. No endpoint uses a login, cookies or anyone's account.

Which leagues and seasons are covered?+

The Premier League (EPL), La Liga, Bundesliga, Serie A, Ligue 1 and the Russian Premier League (RFPL), the leagues Understat covers. Pass season as the starting year, for example 2024 for 2024/25.

Can I use the Understat API from Python?+

Yes. It is a plain HTTPS API, so requests or the API.SH Python SDK work, and the JSON loads straight into a pandas DataFrame. The same works from R, JavaScript or Google Sheets.

How do I get started?+

1. Sign up at api.sh. 2. Copy your API key. 3. Call /understat/v1/league-players with league=EPL and sort=xg. Every parameter is in the docs at https://api.sh/docs. You can also use the JS or Python SDK, Google Sheets, Zapier, Make, n8n or the MCP server at https://api.sh/mcp.