football-docs 0.3.0 → 0.4.0

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

@@ -0,0 +1,81 @@
+---
+source_type: curated
+source_url: https://github.com/statsbomb/open-data
+upstream_version: null
+crawled_at: null
+---
+
+# StatsBomb Identity Surfaces
+
+StatsBomb provides strong match, lineup, event, and tactical context for covered
+competitions. Open Data is excellent for public examples and corroboration, but
+its coverage is selective and should not be treated as a full canonical register
+source unless the exact scope has been audited.
+
+## Access Surface
+
+StatsBomb identity examples can come from the public Open Data repository, the
+`statsbombpy` wrapper, or licensed commercial APIs. Public docs should prefer
+Open Data IDs and explicitly say when guidance is inferred from Open Data rather
+than a commercial entitlement.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | `competition_id` | Stable inside StatsBomb. Pair with `competition_name` and country/region for human review. |
+| Season | `season_id` under a competition | Stable inside StatsBomb. Not globally unique without competition context in some workflows. |
+| Match | `match_id` | Strong match bridge for covered matches. |
+| Team | `team_id` | Strong team bridge inside StatsBomb data. Check whether a single ID is being used across provider-side historical segmentation. |
+| Player | `player_id` | Strong player bridge inside lineups/events. Corroborate with names, DOB from another authority, and relationship evidence. |
+| Coach or manager | lineup or match metadata surfaces where present | Treat as role evidence. Coverage is less central than player/event data. |
+
+## ID Scheme Notes
+
+StatsBomb Open Data exposes numeric `competition_id`, `season_id`, `match_id`,
+`team_id`, and `player_id` fields, plus event UUIDs. The numeric IDs are stable
+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.
+- Matches: match ID, date, home and away team IDs, score, competition, season,
+  match status, and lineup availability.
+- Teams: team IDs and names from matches, lineups, and events.
+- Players: player IDs, names, team membership in lineups/events, shirt number,
+  position, and event participation.
+
+## Known Quirks
+
+- Open Data coverage is selective. Absence from open data is not evidence that
+  an entity or match does not exist.
+- StatsBomb lineups are strong match-grain relationship evidence but not the
+  same as club or national-team contract membership.
+- Public Open Data may include rich international matches but not full
+  tournament squad or call-up semantics.
+- Names can be display names. Use another attribute authority for DOB where a
+  person bridge requires it.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for StatsBomb identity
+surfaces. Reep Next can cite Open Data ID families and matching cautions, while
+commercial entitlement assumptions, register acceptance policy, private review
+evidence, and derived bridge decisions belong outside football-docs.

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.

package/docs/statsbomb/player-mapping.md

@@ -0,0 +1,148 @@
+---
+source_type: curated
+source_url: https://github.com/statsbomb/open-data
+upstream_version: "1.0.0"
+crawled_at: null
+---
+
+# StatsBomb Player Mapping API
+
+The Player Mapping endpoint bridges StatsBomb's **two internal ID systems** —
+the *live* system and the *offline* system — for players, teams, and countries.
+**Commercial API only**; there is no Open Data equivalent.
+
+- Endpoint: `GET https://data.statsbomb.com/api/v1/player-mapping?<params>` (v1)
+- Auth: HTTP Basic (StatsBomb credentials)
+
+## Why this matters: live vs offline IDs
+
+StatsBomb does not have a single player/team/country ID space. The same player
+has a **`live_player_id`** (StatsBomb Live system) and a separate
+**`offline_player_id`** (standard StatsBomb offline system); likewise
+`live_team_id`/`offline_team_id` and `live_country_of_birth_id`/
+`offline_country_of_birth_id`, and `live_match_id`/`offline_match_id`. Which ID
+appears in a given feed depends on the system that produced it. This endpoint is
+the authoritative crosswalk between the two.
+
+Treat StatsBomb IDs as **(system, id)** pairs, not bare integers. A
+`player_id` seen elsewhere is only unambiguous once you know whether it is a
+live or offline id. See `identity-surfaces.md`.
+
+## Request parameters
+
+No query parameters → no data returned. Filters narrow the licensed set:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `competition-id` | integer | Desired competition id |
+| `season-id` | integer | Desired season id |
+| `live-player-id` | integer | Player id from the StatsBomb Live system |
+| `offline-player-id` | integer | Player id from the offline system |
+| `match-date-from` | yyyy-mm-dd | Only competition-season-team blocks with matches on/after this date |
+| `match-date-to` | yyyy-mm-dd | Only blocks with matches on/before this date (combine with `-from` for a window) |
+
+Size/shape controls:
+
+| Parameter | Type | Description |
+|---|---|---|
+| `all-account-data` | boolean | Must be `true` to return all player data on the account (otherwise trimmed, to protect trialling users) |
+| `add-matches-played` | boolean | Must be `true` to include the `matches_played` array per block |
+
+Constraints:
+- `live-player-id` and `offline-player-id` are **mutually exclusive** — supply
+  at most one.
+- If the query would return **more than 5000 records, the response is streamed
+  to a file** as JSON instead of being returned as the inline payload. Plan for
+  both delivery modes.
+- Even when `match-date-from`/`-to` are set, `matches_played` (when requested)
+  still returns **all** matches in the competition-season-team block, not just
+  those in the date window.
+
+Example — Jill Scott, 2020/21 FA WSL, with matches:
+
+```
+https://data.statsbomb.com/api/v1/player-mapping?season-id=90&competition-id=37&offline-player-id=10172&add-matches-played=true
+```
+
+## Response
+
+JSON array of player-mapping blocks. One block per
+**{competition, season, team}** the player appeared for — so a mid-season
+transfer yields multiple blocks for the same player.
+
+| Field | Type | Description |
+|---|---|---|
+| `competition_id` | integer | Competition id (some StatsBomb documentation misspells the key as `competiton_id`; the JSON payload uses `competition_id`) |
+| `competition_name` | string | Competition name |
+| `season_id` / `season_name` | integer / string | Season |
+| `offline_team_id` | integer | Team id (offline system) |
+| `live_team_id` | integer | Team id (Live system) |
+| `team_name` | string | Team name |
+| `team_gender` | string | Gender of competitions played by the team |
+| `earliest_match_date` | yyyy-mm-dd | Earliest match the player appeared in for this block |
+| `most_recent_match_date` | yyyy-mm-dd | Most recent match in this block |
+| `offline_country_of_birth_id` | integer | Country-of-birth id (offline system) |
+| `live_country_of_birth_id` | integer | Country-of-birth id (Live system) |
+| `country_of_birth_name` | string | Country of birth name |
+| `offline_player_id` | integer | Player id (offline system) |
+| `live_player_id` | integer | Player id (Live system) |
+| `player_name` | string | Player name |
+| `player_nickname` | string | Player nickname (nullable) |
+| `player_height` | number | Height (cm) |
+| `player_weight` | number | Weight (kg) |
+| `player_birth_date` | yyyy-mm-dd | Date of birth |
+| `player_preferred_foot` | string | Recognised preferred foot (some StatsBomb documentation misspells the key as `player_perferred_foot`; the JSON payload uses `player_preferred_foot`) |
+| `matches_played` | array | Matches in this block (only if `add-matches-played=true`) |
+
+`matches_played[]` entries:
+
+| Field | Type | Description |
+|---|---|---|
+| `offline_match_id` | integer | Match id (offline system) |
+| `live_match_id` | integer | Match id (Live system) |
+| `match_date` | yyyy-mm-dd | Date the match was played |
+
+### Example response (abridged)
+
+```json
+[ {
+  "competition_id": 37,
+  "competition_name": "FA Women's Super League",
+  "season_id": 90,
+  "season_name": "2020/2021",
+  "offline_team_id": 746,
+  "live_team_id": 389,
+  "team_name": "Manchester City WFC",
+  "team_gender": "female",
+  "earliest_match_date": "2020-09-05",
+  "most_recent_match_date": "2021-01-17",
+  "offline_country_of_birth_id": 68,
+  "live_country_of_birth_id": 2,
+  "country_of_birth_name": "England",
+  "offline_player_id": 10172,
+  "live_player_id": 32564,
+  "player_name": "Jill Scott",
+  "player_nickname": null,
+  "player_height": 181.0,
+  "player_weight": 68.0,
+  "player_birth_date": "1987-02-02",
+  "player_preferred_foot": "Right",
+  "matches_played": [
+    { "match_date": "2020-09-05", "live_match_id": 90335, "offline_match_id": 3764234 }
+  ]
+} ]
+```
+
+Note in the example how the **offline and live ids differ** for player
+(10172 vs 32564), team (746 vs 389), country of birth (68 vs 2), and every
+match — exactly the crosswalk this endpoint exists to provide.
+
+## Relevance to reep
+
+reep is the entity register that answers "who is this player?" and holds
+provider cross-references. This endpoint is the canonical StatsBomb-internal
+crosswalk: a `custom_id` bridge to StatsBomb must record **which system** an id
+belongs to (live vs offline) and can use this endpoint to reconcile the two.
+Mapping only a bare StatsBomb player id without its system risks colliding live
+and offline spaces. The block-per-{competition,season,team} shape also captures
+transfer history within a season, useful as relationship evidence.