football-docs 0.3.0 → 0.4.0

package/README.md

@@ -4,10 +4,20 @@ Searchable football data provider documentation for AI coding agents. Like [Cont
 
 **Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot, Windsurf) to work with football data. Works with any tool that supports MCP.
 
-**What it does:** Gives your AI agent a searchable index of documentation for 16 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, and cross-provider comparisons. Your agent looks up the real docs instead of guessing from training data.
+**What it does:** Gives your AI agent a searchable index of documentation for 15 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons. Your agent looks up the real docs instead of guessing from training data.
 
 **Why not just let the AI figure it out?** LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
 
+## Provider identity facts
+
+football-docs is the public source for provider identity-surface facts: access
+shape, ID schemes, matching fields, provider quirks, and provenance rules.
+Curated Reep-derived notes belong here when they can be stated without private
+register state. They should say whether a fact comes from public docs, public
+page evidence, licensed feed shape, or a reviewed public-safe observation, and
+must not include private paths, credentials, scraper state, action ledgers, mint
+salts, or raw restricted payloads.
+
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
 
 ## Quick start
@@ -92,6 +102,7 @@ Add to `claude_desktop_config.json`:
 - "What is Opta qualifier 76?" (big chance)
 - "How does StatsBomb represent shot events?"
 - "Compare Opta and Wyscout coordinate systems"
+- "Which provider IDs are safe identity bridges for Transfermarkt players?"
 - "Does SportMonks have xG data?"
 - "What event types does kloppy map to GenericEvent?"
 - "How does SPADL represent a tackle?"
@@ -100,18 +111,23 @@ Add to `claude_desktop_config.json`:
 
 | Provider | Chunks | Categories |
 |----------|--------|------------|
-| StatsBomb | 143 | event-types, data-model, coordinate-system, api-access, xg-model |
+| StatsBomb | 150 | event-types, data-model, coordinate-system, api-access, xg-model, identity-surfaces |
 | kloppy | 100 | data-model, usage, provider-mapping |
-| SportMonks | 71 | event-types, data-model, api-access |
+| SportMonks | 78 | event-types, data-model, api-access, identity-surfaces |
 | databallpy | 63 | data-model, overview, usage |
 | mplsoccer | 62 | overview, pitch-types, visualizations |
-| Wyscout | 61 | event-types, data-model, coordinate-system, api-access |
+| Wyscout | 68 | event-types, data-model, coordinate-system, api-access, identity-surfaces |
 | Free sources | 45 | overview, fbref, understat |
 | soccerdata | 40 | overview, data-sources, usage |
-| Opta | 29 | event-types, qualifiers, coordinate-system, api-access |
+| Opta | 36 | event-types, qualifiers, coordinate-system, api-access, identity-surfaces |
 | socceraction | 26 | SPADL format, VAEP, Expected Threat |
+| FotMob | 7 | identity-surfaces |
+| Impect | 7 | identity-surfaces |
+| SkillCorner | 7 | identity-surfaces |
+| Soccerdonna | 7 | identity-surfaces |
+| Transfermarkt | 7 | identity-surfaces |
 
-**640 searchable chunks** across 10 providers.
+**703 searchable chunks** across 15 providers.
 
 ## Contributing
 

package/bin/serve.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-await import(resolve(__dirname, "..", "dist", "index.js"));
+await import(pathToFileURL(resolve(__dirname, "..", "dist", "index.js")).href);

package/docs/fotmob/identity-surfaces.md

@@ -0,0 +1,62 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# FotMob Identity Surfaces
+
+FotMob is useful as a public consumer-facing corroborator for fixtures, teams,
+players, and competition pages. It should generally be treated as a bridge and
+lookup surface rather than as the canonical ontology source.
+
+## Access Surface
+
+FotMob identity evidence usually comes from public web pages or undocumented
+consumer-facing endpoints. Treat access and response shape as mutable, record
+the public URL or endpoint family and snapshot date, and avoid publishing
+scraping bypass or rate-limit evasion details.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | league or tournament ID | Useful public bridge. Check country, gender, season, and competition type. |
+| Season | season ID or season path parameter where exposed | Treat as provider-scoped and audit URL/API stability. |
+| Match | match ID | Strong public match corroborator when fixture fields align. |
+| Team | team ID | Useful for clubs and national teams. Check side type and country. |
+| Player | player ID | Useful public profile bridge. Corroborate with DOB, nationality, team, and position from stronger sources. |
+| Coach or staff | manager profile where exposed | Treat as role evidence unless profile attributes are strong enough. |
+
+## ID Scheme Notes
+
+FotMob IDs are provider-scoped numeric IDs. Match, team, player, league, and
+season IDs are useful bridges, while URL slugs and display labels are handles.
+Because the public endpoint contract is undocumented, store source URL,
+endpoint family, and snapshot date alongside any bridge evidence.
+
+## Useful Matching Fields
+
+- Match: FotMob match ID, date/time, home and away teams, score, league, season,
+  venue, status, lineups, and player stats.
+- Team: team ID, official/display name, country, league participation, squad,
+  and fixtures.
+- Player: player ID, full name, date of birth where present, nationality,
+  position, current team, shirt number, and match participation.
+
+## Known Quirks
+
+- FotMob is optimised for product display. Display names, slugs, and grouping
+  labels may change.
+- Profile and current-team surfaces are point-in-time facts. Keep a snapshot
+  date when using them.
+- Public endpoints may be undocumented. Treat access and response shape as
+  mutable unless the provider documents the contract.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for FotMob identity
+surfaces, public URL families, and matching cautions. Reep Next can cite those
+facts, but private endpoint handling, scrape internals, rate-limit tactics,
+review outcomes, and register decisions belong outside football-docs.

package/docs/impect/identity-surfaces.md

@@ -0,0 +1,61 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Impect Identity Surfaces
+
+Impect is primarily useful as a commercial match and event data provider. Public
+documentation for identity surfaces is limited, so this page records cautious
+curated guidance for entity-resolution work that has legitimate data access.
+
+## Access Surface
+
+Access is through licensed Impect deliveries or customer APIs. Public
+football-docs examples should stay synthetic or describe field families only.
+Record delivery date, competition scope, and whether IDs are documented as
+stable across deliveries before using them as durable bridges.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | provider competition key | Check whether the feed exposes stable competition IDs or only customer-specific names. |
+| Season | provider season or competition-edition key | Treat as provider scoped until audited. |
+| Match | provider match key | Strong bridge if the key is stable in the delivered feed and fixture fields align. |
+| Team | provider team key | Corroborate with match participation, name, country, and side type. |
+| Player | provider player key | Corroborate with lineup/event participation and biographical attributes from another authority. |
+| Staff | provider staff or official key if exposed | Treat as role evidence unless profile attributes are available. |
+
+## ID Scheme Notes
+
+Treat Impect match, team, player, season, and competition keys as opaque
+provider-scoped IDs. Some deliveries may be customer-shaped; do not assume a key
+is globally stable until that is confirmed in the contract or repeated exports.
+
+## Useful Matching Fields
+
+- Match: provider match key, date, home and away teams, score, competition,
+  season, venue, and delivery snapshot.
+- Team: provider team key, names, country, competition participation, and match
+  relationship evidence.
+- Player: provider player key, display name, team in match, lineup status,
+  shirt number, position, and event participation.
+
+## Known Quirks
+
+- Commercial data extracts may be customer-shaped. Confirm whether IDs are
+  stable across deliveries before using them as durable bridges.
+- Event participation is strong relationship evidence, but it does not prove
+  person identity without attribute or external-provider corroboration.
+- If profile attributes are thin, keep Impect as a corroborator rather than a
+  canonical mint source.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Impect identity field
+families and matching cautions. Reep Next can cite those public-safe field
+shapes, but customer deliveries, private IDs, raw feed payloads, and register
+review outcomes belong outside football-docs.

package/docs/opta/identity-surfaces.md

@@ -0,0 +1,71 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Opta / Stats Perform Identity Surfaces
+
+Opta data usually has the strongest structured identity spine for professional
+football projects that have licensed access to the SDAPI feeds. Treat Opta as a
+canonical schedule and structure source only when the local entitlement and
+coverage audit prove that the relevant competition family is complete.
+
+## Access Surface
+
+Primary access is through licensed Stats Perform / Opta feeds or customer
+exports. Public-facing Opta Analyst surfaces can be useful for examples, but
+they are not a substitute for an entitlement-safe feed contract. Record the feed
+family, extraction date, and competition coverage when using Opta identity facts.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | competition or tournament identifiers | Use with tournament-calendar metadata. Names and display labels vary by locale and feed. |
+| Season | tournament calendar UUID | Strong season or tournament-edition key. Split-stage competitions may need parent and child season modelling outside Opta. |
+| Stage or round | stage, phase, group, round, or schedule metadata | Opta is often authoritative for schedule-stage shape, but label strings still need normalisation. |
+| Match | fixture or match UUID | Best canonical match key when schedule coverage is complete. Fixture tuples should corroborate, not define, identity. |
+| Team | contestant UUID | Can represent clubs, national teams, youth teams, reserve sides, or historical contestants. Use type/scope attributes. |
+| Player | person UUID | Strong person key inside Opta. Still corroborate against names, DOB, nationality, and relationship evidence before cross-provider bridging. |
+| Coach or staff | person UUID plus role surface | Person UUIDs can span player and coach roles. Keep role edges separate from person identity. |
+
+## ID Scheme Notes
+
+Opta identifiers are opaque provider keys. Do not parse semantic meaning from
+their string shape, and do not assume that display labels, stage labels, or
+contestant names are stable identifiers. Match, contestant, person, competition,
+and tournament-calendar IDs should be stored with provider, feed family, and
+snapshot metadata.
+
+## Useful Matching Fields
+
+- Match: date/time, home and away contestant UUIDs, score, competition, season,
+  stage, venue, and status.
+- Team: contestant UUID, official name, short name, country, gender, age class,
+  national-team or club scope, and active period where available.
+- Person: Opta person UUID, full name, short name, date of birth, nationality,
+  position, gender, and squad or career memberships.
+- Relationships: schedule team participation, squads, lineups, coaching staff,
+  substitutions, and career memberships.
+
+## Known Quirks
+
+- Opta labels are provider display labels, not ontology. Do not mint a separate
+  competition or team solely because the feed label differs from another
+  provider.
+- Some competitions have full schedule and squad coverage but sparse match-event
+  or lineup tables in a local mirror. Check all person substrates before
+  assuming people cannot be resolved.
+- National teams need explicit team scope and country attributes. Do not encode
+  the full national-team concept only in a club-shaped team type.
+- Some person facts are current-point-in-time surfaces, especially active squad
+  or career listings. Record the snapshot date when using them.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Opta identity surfaces:
+access shape, ID families, matching fields, and known quirks. Reep Next
+acceptance policy, canonical-feed assignments, minting, review cases, action
+ledgers, and private feed observations belong outside football-docs.

package/docs/skillcorner/identity-surfaces.md

@@ -0,0 +1,60 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# SkillCorner Identity Surfaces
+
+SkillCorner is mainly a tracking and physical-data provider. Its identity
+surfaces are most useful for linking delivered match, team, and player rows back
+to an existing register rather than minting a full football ontology.
+
+## Access Surface
+
+Access is through licensed SkillCorner APIs or delivered tracking/physical-data
+files. Public guidance should use synthetic examples or high-level field names,
+not proprietary tracking payloads. Record delivery date, match scope, and data
+product when using SkillCorner identity evidence.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | provider competition key where present | Often secondary to match delivery scope. Audit before treating as canonical. |
+| Season | provider season or delivery context | Keep provider-scoped unless a stable season key is documented in the extract. |
+| Match | provider match key | Strong bridge when fixture fields and delivery metadata agree. |
+| Team | provider team key | Corroborate with match participation and team names. |
+| Player | provider player key | Corroborate with tracking roster, shirt number, position, and external person attributes. |
+
+## ID Scheme Notes
+
+SkillCorner IDs should be treated as opaque and provider-scoped. Match delivery
+IDs, team IDs, and player IDs are strongest when paired with the delivery
+snapshot and fixture context. A tracking roster key is not automatically a
+season membership or person identity without corroborating attributes.
+
+## Useful Matching Fields
+
+- Match: provider match key, date, competition, season, home and away teams,
+  score where present, and data delivery snapshot.
+- Team: provider team key, name, side in match, and relationship to match.
+- Player: provider player key, name, team in match, shirt number, position,
+  starter/substitute status where supplied, and tracking samples.
+
+## Known Quirks
+
+- Tracking feeds can expose matchday rosters without enough biographical detail
+  for safe person minting. Use them as relationship evidence unless another
+  source supplies the identity attributes.
+- Delivery metadata may be more reliable than display names for reproducible
+  matching.
+- A match-level tracking file is not proof of a season-long membership edge.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for SkillCorner identity
+surfaces in tracking and physical-data deliveries. Reep Next can cite the field
+families and matching cautions, but raw tracking payloads, private delivery
+examples, and register review outputs belong outside football-docs.

package/docs/soccerdonna/identity-surfaces.md

@@ -0,0 +1,66 @@
+---
+source_type: curated
+source_url: null
+upstream_version: null
+crawled_at: null
+---
+
+# Soccerdonna Identity Surfaces
+
+Soccerdonna is a useful public corroborator for women's football, particularly
+for teams, competitions, player profiles, staff pages, and match reports. Treat
+it as a public evidence provider whose coverage and structure vary by
+competition and era.
+
+## Access Surface
+
+Soccerdonna is a public website surface. Use public profile pages, competition
+pages, and match reports as corroborating evidence, with the page URL and
+snapshot date recorded. Do not publish private scraping state, retry logs, or
+local mirror paths.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | competition page ID or slug | Useful corroborator. Canonical competition shape should still follow the chosen match feed. |
+| Season | season-scoped competition URL parameters | Can corroborate season membership but may not match a register season hierarchy exactly. |
+| Stage or round | match-report round labels | Useful for stage naming after normalisation. Raw labels should not be minted directly. |
+| Match | match-report or `spielbericht` ID | Strong public match corroborator when date, teams, and score align. |
+| Team | team profile ID | Useful for women's clubs and competition participation. Check gender and side type explicitly. |
+| Player | player profile ID | Useful for names, DOB where present, nationality, position, and career/team membership evidence. |
+| Coach or staff | staff profile ID | Useful for coaching roles, but role labels need a normalised public vocabulary. |
+
+## ID Scheme Notes
+
+Treat profile, team, competition, and match-report IDs as provider-scoped
+bridges. URL text and slugs are handles, not identity. Season and competition
+URL parameters are useful context, but the target register still decides whether
+they map to a season, stage, or competition entity.
+
+## Useful Matching Fields
+
+- Match reports: date, home team, away team, score, competition, round label,
+  lineups, substitutions, and staff.
+- Player and coach profiles: full name, display name, date of birth,
+  nationality, position or role, profile URL, and career memberships.
+- Team pages: official name, competition entries, country, gender context, and
+  match participation.
+
+## Known Quirks
+
+- DOB coverage varies by era and competition. Missing DOB should create review
+  residue rather than forcing a weak name-only bridge.
+- Round labels need normalisation before stage minting. Preserve the raw label
+  as evidence where useful.
+- Soccerdonna can expose people through match reports before profile data has
+  enough identity attributes to bridge safely.
+- Some pages are better corroborators than canonical mint sources because their
+  season and competition hierarchy can differ from the schedule feed.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for Soccerdonna profile,
+team, competition, and match-report identity surfaces. Reep Next can cite those
+facts while keeping review decisions, private scrape state, action logs, and
+women's-football implementation plans outside football-docs.

package/docs/sportmonks/identity-surfaces.md

@@ -0,0 +1,65 @@
+---
+source_type: curated
+source_url: https://docs.sportmonks.com/v3
+upstream_version: null
+crawled_at: null
+---
+
+# SportMonks Identity Surfaces
+
+SportMonks exposes a broad REST API with stable numeric IDs for leagues,
+seasons, stages, fixtures, participants, players, coaches, venues, and related
+entities. It is a useful bridge and corroborator, especially where public API
+access is available.
+
+## Access Surface
+
+Primary access is the documented SportMonks football API. Include expansions can
+make identity, relationship, and event evidence available from the same request,
+but callers should still record the endpoint, include set, plan scope, and
+request date because coverage depends on subscription tier.
+
+## Stable Identity Surfaces
+
+| Entity | Common surface | Notes |
+|---|---|---|
+| Competition | league ID | Strong provider key. League names and display categories should be normalised. |
+| Season | season ID | Strong provider key under a league. Use start/end years and league relationship for review. |
+| Stage or round | stage ID, round ID, group ID | Useful provider structure, but may differ from a canonical schedule feed. |
+| Match | fixture ID | Strong match bridge when date, participants, score, and competition align. |
+| Team | participant ID | Can represent clubs or national teams. Check participant type and country. |
+| Player | player ID | Strong provider key only if not reused or contaminated by previous bridge errors. Corroborate with attributes. |
+| Coach or staff | coach ID | Treat as person identity with role-specific evidence. |
+
+## ID Scheme Notes
+
+SportMonks IDs are numeric provider IDs. Keep them provider-scoped and do not
+merge by bare number across providers. League, season, stage, round, fixture,
+participant, player, coach, and venue IDs should be stored with the source
+endpoint and include path that supplied them.
+
+## Useful Matching Fields
+
+- Fixture: `fixture.id`, league, season, stage, round, participants, start time,
+  scores, state, venue, and lineups.
+- Participant: ID, name, short code, country, gender or type where present, and
+  fixture participation.
+- Player: ID, display name, common name, date of birth, nationality, position,
+  height, weight, image URL, and team/lineup relationships.
+
+## Known Quirks
+
+- Broad APIs can carry legacy or contaminated bridges if a downstream register
+  previously joined the wrong person. Validate same-provider ID uniqueness.
+- Include-based responses can make relationship evidence easy to retrieve, but
+  consumers must still distinguish lineup, squad, current team, and historical
+  membership semantics.
+- Stages and rounds are provider shape. Keep the canonical ontology decision
+  separate from the SportMonks response nesting.
+
+## Reep Next Usage
+
+Use this page as the public provider-fact reference for SportMonks ID families,
+API identity surfaces, include paths, and matching cautions. Reep Next can cite
+those facts, but contaminated-bridge review, private validation output, API
+keys, paid-tier payloads, and register decisions belong outside football-docs.

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.