football-docs 0.3.1 → 0.4.0

package/docs/statsbomb/api-access.md

@@ -172,32 +172,59 @@ The nested JSON objects (pass, shot, carry, etc.) are flattened with underscores
 ## 3. Commercial REST API
 
 **Access**: Requires a paid license from StatsBomb (contact sales@statsbomb.com)
-**Base URL**: `https://data.statsbomb.com/api/v2/`
 
 ### Authentication
 
-HTTP Basic Auth with username (email) and password provided by StatsBomb.
+HTTP Basic Auth with username (email) and password provided by StatsBomb. The
+same credentials work across every endpoint.
 
 ### Endpoints
 
-| Endpoint | Description |
-|----------|-------------|
-| `GET /competitions` | List all licensed competitions |
-| `GET /competitions/{comp_id}/seasons/{season_id}/matches` | Matches for a competition/season |
-| `GET /matches/{match_id}/events` | Events for a match |
-| `GET /matches/{match_id}/lineups` | Lineups for a match |
-| `GET /matches/{match_id}/360-frames` | 360 freeze frames for a match |
+There is **no single base URL or global API version**. Each resource is
+independently versioned and the API spans **two hostnames**
+(`data.statsbombservices.com` and `data.statsbomb.com`). The full host/version
+matrix, query parameters, and caveats (including a host typo in StatsBomb's own
+Team Stats spec) are documented in **`api-endpoints.md`**. Summary:
+
+| Resource | Path (see api-endpoints.md for host + version) |
+|----------|-----------------------------------------------|
+| Competitions | `/api/v4/competitions` |
+| Matches | `/api/v6/competitions/{cid}/seasons/{sid}/matches` |
+| Lineups | `/api/v4/lineups/{mid}` |
+| Events | `/api/v8/events/{mid}` |
+| 360 Frames | `/api/v2/360-frames/{mid}` |
+| Player Mapping | `/api/v1/player-mapping?<params>` |
+| Player Match / Season Stats | `/api/v5/matches/{mid}/player-stats`, `/api/v4/competitions/{cid}/seasons/{sid}/player-stats` |
+| Team Match / Season Stats | `/api/v1/matches/{mid}/team-stats`, `/api/v2/competitions/{cid}/seasons/{sid}/team-stats` |
 
 ### Response Format
 
-The commercial API returns the same JSON structure as the open data files. The only differences are:
-- More competitions and seasons available
-- Data may be more current (open data can lag behind)
-- Some fields may be available earlier in the commercial feed
+For competitions, matches, lineups, events, and 360 frames the commercial API
+returns the same JSON structure as the open data files (more competitions,
+fresher data). The **stats endpoints and player-mapping have no open-data
+equivalent** — see the parity table below and the dedicated docs
+(`player-match-stats.md`, `player-season-stats.md`, `team-match-stats.md`,
+`team-season-stats.md`, `player-mapping.md`, `iq-metrics-glossary.md`).
+
+### Open Data vs Commercial parity
+
+| Capability | Open Data | Commercial API |
+|---|---|---|
+| Competitions / Matches / Lineups / Events / 360 | Yes (selective comps) | Yes (licensed scope) |
+| Player & Team Match/Season Stats (IQ metrics) | **No** | Yes |
+| Player Mapping (live/offline IDs) | **No** | Yes |
+| Freshness | Irregular GitHub updates | Near-live for licensed comps |
+
+Code written against open data cannot read OBV, xGChain, PPDA, PSxG, the IQ
+metric catalogues, or live/offline IDs — these exist only in the commercial
+feed.
 
 ### Rate Limits
 
-The commercial API has rate limits that vary by license tier. StatsBomb recommends caching responses locally and using bulk endpoints where possible.
+The commercial API has rate limits that vary by license tier. StatsBomb
+recommends caching responses locally and polling the Competitions/Matches
+`*_updated` / `last_updated` timestamps to refetch only changed data (see
+`api-endpoints.md` → Incremental sync).
 
 ---
 

package/docs/statsbomb/api-endpoints.md

@@ -0,0 +1,120 @@
+---
+source_type: curated
+source_url: https://github.com/statsbomb/open-data
+upstream_version: null
+crawled_at: null
+---
+
+# StatsBomb Commercial REST API Endpoints
+
+Reference for the StatsBomb commercial REST API surface. Each resource is
+**independently versioned** and the API spans **two hostnames** — there is no
+single global API version or base path.
+
+> This page describes these endpoint versions: Competitions v4.0.0, Matches
+> v6.0.0, Lineups v4.0.1, Events v8.0.0, 360 Frames v2.0.0, Player Mapping
+> v1.0.0, Player Match Stats v5.0.0, Player Season Stats v4.0.0, Team Match
+> Stats v1.0.0, Team Season Stats v2.0.0. StatsBomb increments the version
+> segment per resource when the response shape changes, so the URL itself
+> tells you which version a feed is; a higher version than listed here may
+> carry additional fields not described on this page.
+
+## Authentication
+
+All endpoints use **HTTP Basic Auth** with the username (email) and password
+issued by StatsBomb. The same credentials work across every endpoint. Access
+requires a paid licence; licensed scope determines which competitions/seasons
+return data.
+
+`statsbombpy` and `StatsBombR` wrap these endpoints. With `statsbombpy`, set
+`SB_USERNAME`/`SB_PASSWORD` env vars or pass `creds={"user":..., "passwd":...}`.
+
+## Endpoint matrix
+
+`{cid}` = competition_id, `{sid}` = season_id, `{mid}` = match_id.
+
+| Resource | Method + path | Host | Spec version |
+|---|---|---|---|
+| Competitions | `GET /api/v4/competitions` | `data.statsbombservices.com` | v4.0.0 |
+| Matches | `GET /api/v6/competitions/{cid}/seasons/{sid}/matches` | `data.statsbombservices.com` | v6.0.0 |
+| Lineups | `GET /api/v4/lineups/{mid}` | `data.statsbomb.com` | v4.0.1 |
+| Events | `GET /api/v8/events/{mid}` | `data.statsbombservices.com` | v8.0.0 |
+| 360 Frames | `GET /api/v2/360-frames/{mid}` | `data.statsbombservices.com` | v2.0.0 |
+| Player Mapping | `GET /api/v1/player-mapping?<params>` | `data.statsbomb.com` | v1.0.0 |
+| Player Match Stats | `GET /api/v5/matches/{mid}/player-stats` | `data.statsbombservices.com` | v5.0.0 |
+| Player Season Stats | `GET /api/v4/competitions/{cid}/seasons/{sid}/player-stats` | `data.statsbombservices.com` | v4.0.0 |
+| Team Match Stats | `GET /api/v1/matches/{mid}/team-stats` | `data.statsbomb.com` | v1.0.0 |
+| Team Season Stats | `GET /api/v2/competitions/{cid}/seasons/{sid}/team-stats` | `data.statsbombservices.com` | v2.0.0 |
+
+Older versions of a resource are generally reachable by lowering the version
+segment (e.g. `/api/v7/events/{mid}`), subject to StatsBomb retaining them.
+
+### Host and typo caveats
+
+- **Two active hosts.** Most resources are on `data.statsbombservices.com`;
+  Lineups and Player Mapping are documented on `data.statsbomb.com`. The hosts
+  are not interchangeable in the specs — use the one documented per resource and
+  verify against live behaviour.
+- **Team Match Stats typo.** The Team Match Stats v1.0.0 PDF prints the host as
+  `data.statsbom.com` (missing a `b`). This is a documentation typo; the
+  intended host is almost certainly `data.statsbomb.com`. Treat with caution and
+  confirm against StatsBomb support.
+
+## Response format
+
+Every endpoint returns a JSON **array** of objects. The shape mirrors the
+StatsBomb Open Data JSON for the entities that exist in open data
+(competitions, matches, lineups, events, 360-frames). The four stats endpoints
+and player-mapping have no open-data equivalent.
+
+| Resource | Array element | Documented in |
+|---|---|---|
+| Competitions | competition-season object | `data-model.md` |
+| Matches | match object (incl. `collection_status`, `metadata`) | `data-model.md` |
+| Lineups | per-team lineup (lineup/formations/events arrays) | `data-model.md` |
+| Events | event object (v8 fields incl. OBV, pass clusters) | `event-types.md` |
+| 360 Frames | freeze-frame object per event_uuid | `data-model.md`, `coordinate-system.md` |
+| Player Mapping | competition-season-team block per player | `player-mapping.md` |
+| Player Match/Season Stats | one row per player | `player-match-stats.md`, `player-season-stats.md` |
+| Team Match/Season Stats | one row per team | `team-match-stats.md`, `team-season-stats.md` |
+
+## Open Data vs commercial parity
+
+The free Open Data repository (`github.com/statsbomb/open-data`) mirrors only a
+subset of the commercial API:
+
+| Capability | Open Data | Commercial API |
+|---|---|---|
+| Competitions / Matches / Lineups / Events / 360 | Yes (selective competitions) | Yes (licensed scope) |
+| Player Match Stats | **No** | Yes (`/matches/{mid}/player-stats`) |
+| Player Season Stats | **No** | Yes (`/competitions/{cid}/seasons/{sid}/player-stats`) |
+| Team Match Stats | **No** | Yes (`/matches/{mid}/team-stats`) |
+| Team Season Stats | **No** | Yes (`/competitions/{cid}/seasons/{sid}/team-stats`) |
+| Player Mapping (live/offline IDs) | **No** | Yes (`/player-mapping`) |
+| Data freshness | Irregular GitHub updates | Near-live for licensed comps |
+
+The pre-computed IQ metric catalogues (OBV, xGChain, PPDA, PSxG, GSAA, etc.)
+and the live/offline ID mapping **only exist in the commercial feed**. Code
+written against open data cannot read these fields — do not assume their
+presence from open-data examples.
+
+## Incremental sync
+
+The Competitions response carries `match_updated`, `match_updated_360`,
+`match_available`, and `match_available_360` timestamps per competition-season;
+the Matches response carries `last_updated` / `last_updated_360` per match.
+Poll Competitions, diff the timestamps, then refetch only changed
+competition-seasons/matches rather than re-pulling everything.
+
+`match_status` must be `"available"` before Events can be fetched for a match;
+`match_status_360` of `"available"` is required before 360 frames exist. See the
+collection/match status enums in `data-model.md`.
+
+## Player Mapping request rules
+
+`/api/v1/player-mapping` requires at least one query parameter (no params = no
+data). `all-account-data=true` is required to return the full licensed set
+(otherwise the response is trimmed for trialling). If a query would return
+**more than 5000 records the response is streamed to a file** as JSON rather
+than returned inline. See `player-mapping.md` for parameters and the
+live/offline ID model.

package/docs/statsbomb/data-model.md

@@ -98,9 +98,49 @@ File: `matches/{competition_id}/{season_id}.json`
 
 ### Data Quality Flags
 
-- `data_version` -- spec version (current: `"1.1.0"`)
-- `shot_fidelity_version` -- `"1"` (basic) or `"2"` (enhanced, includes freeze frames on shots)
-- `xy_fidelity_version` -- `"1"` (less precise locations) or `"2"` (high-precision x/y coordinates)
+`metadata` (object on each match; child attributes are optional and the object
+is empty for matches not yet `available`):
+
+- `data_version` -- the event-data collection version applied to this match (e.g. `1.0.0`, `1.0.1`, `1.0.2`, `1.0.3`, `1.1.0`). Which optional event fields are populated depends on this value; `1.1.0` is the fullest.
+- `shot_fidelity_version` -- `"1"` (basic) or `"2"` (high-fidelity x/y on shots, freeze frames and shot-paired events)
+- `xy_fidelity_version` -- `"1"` (standard location granularity) or `"2"` (high-precision x/y coordinates)
+
+### Match & collection status (Matches API v6)
+
+The Matches response carries several status fields. Events/360 are only
+fetchable once the relevant status reaches `available`:
+
+| Field | Values |
+|---|---|
+| `match_status` | `available` (event data obtainable), `scheduled`, `deleted` |
+| `match_status_360` | `available`, `scheduled` (awaiting 360), `unscheduled` (comp gets no 360) |
+| `play_status` | `Normal`, `Postponed`, `Cancelled`, `Abandoned`, `Forfeited` |
+| `collection_status` | collection pipeline state (16 values, below) |
+
+`collection_status` values: `Unassigned` (not started), `InProgress`,
+`WithoutLocation` (events not yet located on pitch), `WithoutFreezeFrame` (shot
+freeze-frame phase), `PendingValidation`, `Validating`, `Invalid`,
+`WithoutDirection`, `Complete`, `Postponed`, `NoVidError` (footage not sourced),
+`IncVidError` (incomplete footage), `PoorVidError`, `ErrorAbandoned`,
+`ErrorCancelled`, `ErrorForfeit`.
+
+Use `last_updated` / `last_updated_360` per match (and the Competitions
+`match_updated*` / `match_available*` timestamps) to drive incremental sync —
+see `api-endpoints.md`.
+
+### Competition stages
+
+`competition_stage` is an `{id, name}` pair. Stage IDs (from Matches/Events
+specs): 1 Regular Season, 2 Play-In Round, 6 Europa League Play-offs –
+Semi-finals, 8 MLS Cup – Conference Semi-finals, 9 3rd Qualifying Round,
+10 Group Stage, 11 Quarter-finals, 12 Europa League Play-offs – Finals,
+13 16th Finals, 14 Promotion Play-offs – Final, 15 Semi-finals, 18 Promotion
+Play-offs – Semi-finals, 19 Preliminary Round, 20 2nd Round, 21 Europa League
+Play-offs – Quarter-finals, 22 2nd Qualifying Round, 23 MLS Cup – Conference
+Finals, 24 Promotion Play-offs – 1st Round, 25 3rd Place Final, 26 Final,
+27 Promotion Play-offs – 2nd Round, 28 Play-offs, 29 1st Qualifying Round,
+31 Preliminary Round – Semi-finals, 33 8th Finals, 34 1st Phase, 35 Preliminary
+Round – Final.
 
 ---
 
@@ -316,11 +356,14 @@ Every event is tagged with how the current possession started (counter-attack, s
 
 ## Data Versions
 
-| Version | Field | Notes |
-|---------|-------|-------|
-| `data_version` | `1.0.0` | Original spec |
-| `data_version` | `1.1.0` | Current spec with carries, enhanced events |
-| `shot_fidelity_version` | `"1"` | Basic shot data |
-| `shot_fidelity_version` | `"2"` | Enhanced shots with freeze frames |
-| `xy_fidelity_version` | `"1"` | Standard coordinate precision |
-| `xy_fidelity_version` | `"2"` | High-precision coordinates |
+Each match's `metadata` reports the collection versions applied to it. The
+values you may see, side by side:
+
+| Field | Value | What this match contains |
+|-------|-------|--------------------------|
+| `data_version` | `1.0.0` | Core event set, no carry events |
+| `data_version` | `1.1.0` | Full event set including carries and the additional event attributes described on this page and in `event-types.md` |
+| `shot_fidelity_version` | `"1"` | Shots at standard location granularity |
+| `shot_fidelity_version` | `"2"` | Shots, their freeze frames, and shot-paired events at high-precision x/y |
+| `xy_fidelity_version` | `"1"` | Standard x/y location granularity |
+| `xy_fidelity_version` | `"2"` | High-precision x/y coordinates |

package/docs/statsbomb/event-types.md

@@ -9,6 +9,7 @@ StatsBomb uses named event types with numeric IDs. Every event in a match has a
 | 2 | Ball Recovery | Player regains possession from a loose ball |
 | 3 | Dispossessed | Player loses the ball through opponent action (not a failed dribble) |
 | 4 | Duel | Contested situation between two players (aerial or ground) |
+| 5 | Camera On* | Signals the camera resuming gameplay capture after a replay/cut (deprecated; superseded by `off_camera`) |
 | 6 | Block | Player blocks a shot, pass, or cross |
 | 8 | Offside | Player caught in an offside position |
 | 9 | Clearance | Defensive action to remove the ball from a dangerous area |
@@ -18,10 +19,12 @@ StatsBomb uses named event types with numeric IDs. Every event in a match has a
 | 17 | Pressure | Player applies pressure on an opponent in possession |
 | 18 | Half Start | Marks the start of each half/period |
 | 19 | Substitution | Player substitution |
+| 20 | Own Goal Against | An own goal scored against the team |
 | 21 | Foul Won | Player wins a foul from an opponent |
 | 22 | Foul Committed | Player commits a foul |
 | 23 | Goal Keeper | Goalkeeper-specific actions (saves, punches, claims, etc.) |
 | 24 | Bad Behaviour | Disciplinary action not linked to a foul (e.g. dissent) |
+| 25 | Own Goal For | An own goal scored for the team |
 | 26 | Player On | Player enters the pitch (substitution on) |
 | 27 | Player Off | Player leaves the pitch (substitution off) |
 | 28 | Shield | Player shields the ball from an opponent |
@@ -30,12 +33,20 @@ StatsBomb uses named event types with numeric IDs. Every event in a match has a
 | 34 | Half End | Marks the end of each half/period |
 | 35 | Starting XI | Starting lineup announcement (one per team per match) |
 | 36 | Tactical Shift | Formation or positional change during play |
+| 37 | Error | Player makes an on-the-ball mistake that leads to a shot on goal |
 | 38 | Miscontrol | Player fails to control the ball cleanly |
 | 39 | Dribbled Past | Player is beaten by an opponent's dribble |
 | 40 | Injury Stoppage | Play stopped due to injury |
+| 41 | Referee Ball-Drop | Referee drops the ball to resume play after an injury stoppage |
 | 42 | Ball Receipt* | Player receives a pass (the asterisk is part of the name) |
 | 43 | Carry | Player moves with the ball at their feet between events |
 
+> The event-type vocabulary and field set below describe the **Events API
+> v8.0.0** feed (`GET /api/v8/events/{match_id}`). Each match also carries a
+> `metadata.data_version` string (see `data-model.md`) — the exact set of
+> fields present on a given match depends on the data version it was collected
+> under.
+
 ---
 
 ## Common Event Fields
@@ -76,6 +87,25 @@ Every event shares these base fields:
 - `duration` -- event duration in seconds (0.0 for instantaneous events)
 - `related_events` -- UUIDs of causally linked events (e.g. pass -> receipt)
 - `under_pressure` -- boolean, present and true when a defender is applying pressure
+- `off_camera` -- boolean, present and true only when the event occurred while the camera was off (data then logically inferred)
+- `out` -- boolean, present and true when the event's outcome is the ball going out of bounds
+- `counterpress` -- boolean, on various defensive events (pressure, dribbled past, 50-50, duel, block, interception, non-offensive foul committed): a pressing action within 5 seconds of an open-play turnover
+
+### On-Ball Value fields
+
+OBV-eligible events carry net/before/after value fields measuring the change in
+scoring/conceding likelihood caused by the event:
+
+- `obv_for_after`, `obv_for_before`, `obv_for_net` -- scoring likelihood within the possession chain after/before/net
+- `obv_against_after`, `obv_against_before`, `obv_against_net` -- conceding likelihood in the next possession chain
+- `obv_total_net` -- net expected goal-difference change over the next two possession chains
+
+OBV is populated only where play is not interrupted by off-ball events.
+Eligible types: Carry, Ground/High/Low Pass, Dribble, Shot, Goalkeeper
+Collection, Block, Tackle, Interception, Clearance, Goalkeeper Sweep,
+Goalkeeper Save, Foul Committed, Goalkeeper Concede. See
+`iq-metrics-glossary.md` for the OBV concept and its aggregated forms in the
+stats endpoints.
 
 ---
 
@@ -103,7 +133,12 @@ The `shot` object is nested within shot events.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `statsbomb_xg` | float | StatsBomb expected goals value (0.0 to 1.0) |
+| `statsbomb_xg` | float | xG "chance quality" -- likelihood of scoring from the shot situation (location, GK and blocker positions), **not** considering shot execution |
+| `gk_save_difficulty_xg` | float | Likelihood of the keeper conceding, given shot placement/velocity and keeper position (on-target, unblocked shots only). Some feeds label this field `statsbomb_xg2` |
+| `shot_execution_xg` | float | Likelihood of scoring after execution -- incorporates placement & velocity on top of the `statsbomb_xg` features |
+| `shot_execution_xg_uplift` | float | `shot_execution_xg − statsbomb_xg`; how much execution improved (or, if negative, worsened) the chance |
+| `gk_positioning_xg_suppression` | float | Goal-scoring threat suppressed by the keeper's positioning vs an average keeper |
+| `gk_shot_stopping_xg_suppression` | float | Goals prevented above expectation by the keeper's shot-stopping |
 | `end_location` | [x, y] or [x, y, z] | Where the shot ended up. Z is height in yards (present for shots that leave the ground) |
 | `key_pass_id` | string | UUID of the pass that assisted this shot |
 | `technique` | object | How the shot was struck |
@@ -207,6 +242,12 @@ The `pass` object is nested within pass events.
 | `no_touch` | boolean | Player intended the ball to run through |
 | `miscommunication` | boolean | Pass and recipient miscommunicated |
 | `backheel` | boolean | Whether the pass was a backheel |
+| `deflected` | boolean | Pass was deflected (can occur on complete or incomplete passes) |
+| `aerial_won` | boolean | The pass event was also an aerial duel won |
+| `pass_cluster_id` | integer | Which of 60 distinct pass clusters this pass is most associated with |
+| `pass_cluster_label` | string | Text description of that cluster, combining its starting third, side of the pitch, length (long/short), primary direction, and modal pass height |
+| `pass_cluster_probability` | float | Probability the pass belongs to `pass_cluster_id`/`label` |
+| `pass_success_probability` | float | Estimated likelihood of the attempted pass being completed, given pitch location, context and target |
 
 ### Pass Types
 

package/docs/statsbomb/identity-surfaces.md

@@ -37,6 +37,22 @@ StatsBomb Open Data exposes numeric `competition_id`, `season_id`, `match_id`,
 inside the provider dataset but should stay provider-scoped. Do not infer global
 identity from a bare number without provider and dataset context.
 
+### Two internal ID systems: live vs offline
+
+StatsBomb does **not** have a single ID space. Internally there is a *live*
+system and an *offline* system, each with its own ids for players, teams,
+country-of-birth, and matches (`live_player_id` vs `offline_player_id`,
+`live_team_id` vs `offline_team_id`, `live_match_id` vs `offline_match_id`,
+etc.). The same person/team has different integers in each. Which system's ids
+appear in a given feed depends on the system that produced it.
+
+Treat a StatsBomb id as a **(system, id)** pair, not a bare integer. Reconciling
+the two requires the commercial **Player Mapping** endpoint
+(`/api/v1/player-mapping`), which returns paired `live_*`/`offline_*` ids — see
+`player-mapping.md`. Open Data does not expose this duality or the mapping
+endpoint, so Open-Data-only workflows generally see one system's ids and should
+record which.
+
 ## Useful Matching Fields
 
 - Competitions and seasons: IDs, names, country, gender, and season label.

package/docs/statsbomb/iq-metrics-glossary.md

@@ -0,0 +1,223 @@
+---
+source_type: curated
+source_url: https://github.com/statsbomb/open-data
+upstream_version: null
+crawled_at: null
+---
+
+# StatsBomb IQ Metrics Glossary
+
+Definitions of the derived metrics that recur across the StatsBomb commercial
+stats endpoints (`player-match-stats`, `player-season-stats`,
+`team-match-stats`, `team-season-stats`) and, for OBV/xG, the Events feed.
+These concepts are referenced by many column names — read this alongside the
+per-endpoint catalogues.
+
+These metrics are commercial-only unless noted. OBV and the xG-decomposition
+fields also appear on individual events; everything else is delivered
+pre-aggregated by the stats endpoints.
+
+## On-Ball Value (OBV)
+
+OBV models the change in the likelihood of scoring/conceding caused by an event,
+expressed in expected-goal-difference units.
+
+On an **event** (Events v8) it appears decomposed as:
+- `obv_for_after` / `obv_for_before` — probability of scoring within the
+  possession chain after / before the event.
+- `obv_for_net` — net change in scoring likelihood from the event.
+- `obv_against_after` / `obv_against_before` / `obv_against_net` — same for the
+  likelihood of conceding in the next possession chain.
+- `obv_total_net` — net change in expected goal difference (scoring change minus
+  conceding change) over the next two possession chains.
+
+OBV is only populated where the sequence of play is not interrupted by off-ball
+events. Event types eligible for OBV: Carry, Ground/High/Low Pass, Dribble,
+Shot, Goalkeeper Collection, Block, Tackle, Interception, Clearance, Goalkeeper
+Sweep, Goalkeeper Save, Foul Committed, Goalkeeper Concede.
+
+In the **stats** endpoints OBV is aggregated and split by action family:
+`*_obv` (total), `*_obv_pass`, `*_obv_shot`, `*_obv_defensive_action`,
+`*_obv_dribble_carry`, `*_obv_gk`. Team stats add `*_obv_*_conceded` (opponent
+OBV). Season uses `_90` / `_pg` suffixes.
+
+## xGChain and xGBuildup
+
+Both attribute the xG of a possession's final shot to **every player involved in
+that possession**, not just the shooter/assister.
+
+- **xGChain** — credits all players who touched the ball during a possession
+  that ended in a shot, with the shot's xG.
+- **xGBuildup** — the same, but **excludes** the shooter and the assisting
+  (key) pass, isolating contribution to build-up play prior to the chance.
+
+Variants across the stats endpoints: `xgchain` / `xgbuildup`, `op_*` (open play
+only), `*_per_possession`, and `_90` / `_pg` season forms.
+
+## xG, npxG, xA and combined measures
+
+- `np_xg` — non-penalty expected goals (xG excluding penalty shots).
+- `np_xg_per_shot` — shot-quality proxy: average npxG per shot taken.
+- `xa` / `op_xa` / `sp_xa` — expected assists: the xG of the shot a player's
+  pass set up (all / open play / set piece).
+- `npxgxa` (season) — non-penalty xG + xA combined goal contribution.
+- `over_under_performance` (season) — actual goal contribution minus expected
+  (xG+xA): finishing/creation over- or under-performance.
+- `conversion_ratio` / `penalty_conversion_ratio` — % of (non-penalty / penalty)
+  shots converted to goals.
+
+## Post-Shot xG (PSxG) and goalkeeping value
+
+PSxG models goal probability **after** the shot is struck, using placement and
+velocity — only defined for on-target, unblocked shots. Used to value
+goalkeeping.
+
+- `np_psxg` — non-penalty PSxG earned from a player's on-target shots.
+- `npot_psxg_faced` / `np_psxg_faced_90` — non-penalty on-target PSxG faced by a
+  goalkeeper.
+- `gsaa` (Goals Saved Above Average) — goals the keeper saved/conceded versus
+  expectation (PSxG faced minus goals conceded). `gsaa_ratio` expresses it as a
+  share of shots faced. `xs_ratio` (season) — expected save % given PSxG faced.
+- `save_ratio` — % of on-target shots saved.
+- `gk_positioning_error` / `np_optimal_gk_dlength` — average distance of the
+  keeper from the modelled optimal position for facing a shot.
+- `da_aggressive_distance` — average distance from goal at which the keeper
+  performs defensive actions (sweeping tendency).
+- `ccaa` / `clcaa` — Claimable Collection Attempts over Average: how often the
+  keeper attempts to claim a claimable pass vs the average keeper.
+- `claim_success` — % of claim attempts that succeed.
+- `goals_conceded` (player-match) — goals conceded by the keeper, excluding
+  penalties and own goals.
+
+The Events v8 shot object decomposes shot xG into: `statsbomb_xg` (chance
+quality — pre-strike situation including GK/defender positions),
+`shot_execution_xg` (incorporates placement & velocity),
+`shot_execution_xg_uplift` (`shot_execution_xg − statsbomb_xg`; can be
+negative), `gk_save_difficulty_xg` (renamed from `statsbomb_xg2`; difficulty for
+the keeper given placement/velocity/position), `gk_positioning_xg_suppression`
+and `gk_shot_stopping_xg_suppression` (threat suppressed by keeper positioning /
+shot-stopping). See `xg-model.md`.
+
+## PPDA — Passes Per Defensive Action
+
+`ppda` (team stats) — how many passes a team allows the opponent before making a
+defensive action (tackle, interception, foul). Lower = more intense pressing.
+StatsBomb defines it in attacking areas: from 40% of pitch length away from the
+pressing team's own goal and forward. `defensive_distance_ppda` is the average
+distance from a team's own goal at which it makes those defensive actions.
+
+## Pressing and counterpressing
+
+- `pressures` — times a player/team pressures an opponent in possession.
+- `counterpressures` — pressures within 5 seconds of the team losing the ball
+  (an open-play turnover).
+- `pressure_regains` / `counterpressure_regains` /
+  `defensive_action_regains` — ball won back within 5 seconds of a pressure /
+  counterpressure / any defensive action.
+- `pressured_action_fails` / `counterpressured_action_fails` — opponent actions
+  forced to fail under (counter)pressure.
+- `aggressive_actions` — tackles, pressures and fouls within 2 seconds of an
+  opposition ball receipt. `aggression` — the proportion of an opponent's pass
+  receipts so contested.
+- `fhalf_*` — restricted to the opposition (final) half of the pitch;
+  `fhalf_*_ratio` expresses it as a share of the player's/team's total.
+- `defensive_distance` — average distance from a team's own goal at which it
+  makes defensive actions (higher = higher defensive line / more proactive).
+
+## Possession-adjusted defensive metrics (padj_*)
+
+`padj_clearances`, `padj_interceptions`, `padj_pressures`, `padj_tackles`,
+`padj_tackles_and_interceptions` (season, per-90) — raw counts adjusted
+proportionally to the team's possession volume, so low-possession teams' high
+raw defensive counts are normalised for fair cross-team comparison.
+
+## Progression and territory
+
+- `deep_progressions` — passes, dribbles and carries into the opposition final
+  third.
+- `deep_completions` — successful passes within ~20 m of the opposition goal.
+- `passes_into_box` / `op_passes_into_box` — successful passes into the box from
+  outside it (all / open play).
+- `passes_inside_box` — passes completed both starting and ending in the box.
+- `directness` (team) — distance gained towards goal during a shot-ending
+  possession divided by total distance travelled in the build-up (1.0 = perfectly
+  direct).
+- `pace_towards_goal` (team) — average build-up speed (m/s) from start of
+  possession to shot, for shot-ending possessions.
+- `pass_length` family — `s_pass_length` (avg completed), `p_pass_length` /
+  `ps_pass_length` (under pressure), `pass_length_ratio` (completed length ÷
+  attempted length), `pressured_change_in_pass_length`.
+- Pass-direction proportions (season) — `forward_pass_proportion`,
+  `backward_pass_proportion`, `sideways_pass_proportion` (and `op_f3_*`
+  variants). Direction is defined by radian arcs of the pass-angle circle:
+  forwards = 11π/6→π/6, backwards = 5π/6→7π/6, sideways = the two remaining
+  arcs, where angle 0 = no change in y (towards the opponent goal line).
+
+## Line-Breaking Passes (LBP) — requires 360 data
+
+A pass is line-breaking when it crosses a defensive line (a row of sufficiently
+close defenders) and makes enough progression toward the centre of the goal.
+360 data also carries this as a per-event `line_breaking_pass` boolean. The
+stats endpoints expose a large LBP suite:
+
+- `lbp` / `lbp_completed` / `lbp_ratio` — attempted / completed / success %.
+- `fhalf_*` and `f3_*` — restricted to opposition half / final third.
+- `obv_lbp` — pass-OBV from line-breaking passes.
+- `lbp_received` — line-breaking passes received.
+- `lbp_to_space_{2,5,10}` — completed LBPs whose recipient had >2/5/10 m of
+  space; `*_received` variants; `average_lbp_to_space_distance` /
+  `*_received_distance` — average space of the recipient.
+
+These (and the `ball_receipts_in_space_{2,5,10}`,
+`average_space_received_in`, `*_passes_360`, `*_ball_receipts_360`,
+`360_minutes`) metrics are derived from 360 data and only populated for matches
+that have it. **Per-90 conversion for 360-derived season metrics uses
+`player_season_360_minutes` / `team_season` 360 minutes, not the standard
+minutes field** — see `player-season-stats.md`.
+
+## Ball receipts in space (360)
+
+- `average_space_received_in` — average value of space for all ball receipts
+  (`fhalf_` / `f3_` variants for opposition half / final third).
+- `ball_receipts_in_space_{2,5,10}` — share of ball receipts made with more than
+  2/5/10 m of space. The 5 m set is a subset of the 2 m set; the 10 m set is a
+  subset of both.
+
+## Outcome / involvement scores
+
+- `positive_outcome_score` — how frequently the player is involved, while on the
+  pitch, in sequences that resolve with a positive outcome (a shot, a free kick
+  in the attacking half, or a corner).
+- `positive_outcome` (season count) — possessions that connected through the
+  player and ended in such an outcome.
+- `defensive_actions` — tackles, pressure events and fouls recorded
+  (`_90` per-90 in season).
+- `shot_touch_ratio` — shots taken as a proportion of touches.
+- `challenge_ratio` — % of duels entered where the player makes a tackle rather
+  than being dribbled past. `dribble_faced_ratio` — % of faced dribbles that
+  were stopped.
+- `change_in_passing_ratio` (season) — pressured pass % minus overall pass %.
+
+## Set-piece breakdown (team stats)
+
+Team stats split attacking and conceding output by set-piece type: `corner`,
+`free_kick` (indirect), `direct_free_kick`, `throw_in`, and aggregate `sp`.
+For each: counts, `*_xg`, `xg_per_*`, `shots_from_*`, `goals_from_*`, and
+`*_shot_ratio` / `*_goal_ratio`, each with a `_conceded` mirror. Also
+`counter_attacking_shots` (shots within 15 s of a possession from own half),
+`high_press_shots` (shots from possessions won within 5 s of a defensive action
+in the opposition half), `shots_in_clear` (only the keeper between shooter and
+goal) — all with `_conceded` mirrors.
+
+## Suffix conventions
+
+- `op_` — open play only (excludes set pieces).
+- `np_` — non-penalty (excludes penalty shots/goals).
+- `sp_` — set piece only.
+- `fhalf_` — opposition (final) half of the pitch.
+- `f3_` — final third.
+- `padj_` — possession-adjusted.
+- `_90` — per 90 minutes (player-season; uses `360_minutes` for 360 metrics).
+- `_pg` — per game (team-season).
+- `_conceded` — the value allowed to/by the opponent (team stats).
+- `*_ratio` — a percentage or proportion.