Skip to content
Back to search

football-docs

Searchable football data provider documentation for AI coding agents. Like Context7 for football data.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/withqwerty/football-docs with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/withqwerty/football-docs'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/withqwerty--football-docs/badge.svg)](/listings/withqwerty--football-docs)

HTML

<a href="/listings/withqwerty--football-docs"><img src="/api/listings/withqwerty--football-docs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The server needs Node.js 22.13 or newer. It uses Node's built-in SQLite, so no native module is compiled at install time.

Claude Code

claude mcp add football-docs -- npx -y football-docs

Cursor

Settings → MCP → Add server. Use this config:

{
  "mcpServers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

VS Code / Copilot

Add to `.vscode/mcp.json`:

{
  "servers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

Claude Desktop

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

After an update

`npx` updates its cached copy of football-docs in place. A server that was already running keeps the old version until it restarts, and its replies then start with a note: "football-docs on disk is now vX, but this server is still running vY". Reconnect the server to fix it (in Claude Code: `/mcp`, then reconnect football-docs).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 578 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # football-docs
  2. Searchable football data provider and tooling documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
  3. **Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.
  4. **What it does:** Gives your AI agent a searchable index of documentation for 31 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, fast-forward, unravelsports, and more), and the APIs of wearable and sports-science vendors (STATSports, Firstbeat, Hawkin Dynamics, VALD). Your agent looks up the real docs instead of guessing from training data.
  5. **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.
  6. ## Strategy
  7. football-docs is intended to be a community-owned, source-transparent Context7
  8. for football data. The public operating contract is in
  9. [STRATEGY.md](STRATEGY.md): what belongs here, what must stay out, how we handle
  10. public-safe provider facts, and how contributors should prove retrieval quality.
  11. ## Provider identity facts
  12. football-docs is the public source for provider identity-surface facts: access
  13. shape, ID schemes, matching fields, provider quirks, and provenance rules.
  14. Curated provider identity notes belong here when they can be stated as public
  15. facts about the provider. They should say whether a fact comes from public docs,
  16. public page evidence, licensed feed shape, or a reviewed public-safe
  17. observation, and must not include credentials, local paths, internal tooling
  18. details, or restricted payloads from any private project.
  19. MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
  20. ## Quick start
  21. The server needs Node.js 22.13 or newer. It uses Node's built-in SQLite, so no
  22. native module is compiled at install time.
  23. ### Claude Code
  24. ```bash
  25. claude mcp add football-docs -- npx -y football-docs
  26. ```
  27. ### Cursor
  28. Settings → MCP → Add server. Use this config:
  29. ```json
  30. {
  31. "mcpServers": {
  32. "football-docs": {
  33. "command": "npx",
  34. "args": ["-y", "football-docs"]
  35. }
  36. }
  37. }
  38. ```
  39. ### VS Code / Copilot
  40. Add to `.vscode/mcp.json`:
  41. ```json
  42. {
  43. "servers": {
  44. "football-docs": {
  45. "command": "npx",
  46. "args": ["-y", "football-docs"]
  47. }
  48. }
  49. }
  50. ```
  51. ### Claude Desktop
  52. Add to `claude_desktop_config.json`:
  53. ```json
  54. {
  55. "mcpServers": {
  56. "football-docs": {
  57. "command": "npx",
  58. "args": ["-y", "football-docs"]
  59. }
  60. }
  61. }
  62. ```
  63. ### After an update
  64. `npx` updates its cached copy of football-docs in place. A server that was
  65. already running keeps the old version until it restarts, and its replies then
  66. start with a note: "football-docs on disk is now vX, but this server is still
  67. running vY". Reconnect the server to fix it (in Claude Code: `/mcp`, then
  68. reconnect football-docs).
  69. ## Tools
  70. | Tool | Description |
  71. |------|-------------|
  72. | `search_docs` | Full-text search across all provider docs. Filter by provider. Results include provenance (source URL, version), mark partial matches, name query terms that no indexed doc mentions, and say when a query names a provider that is not indexed (the `not_indexed` list in `providers.json` gives the reason). |
  73. | `resolve_provider_id` | Resolve provider names and aliases to canonical indexed provider keys before searching. |
  74. | `get_provider_docs` | Retrieve docs for a resolved provider, optionally filtered by topic or category. |
  75. | `list_providers` | List all indexed providers and their doc coverage. |
  76. | `compare_providers` | Compare how different providers handle the same concept. |
  77. | `request_update` | Request a new provider, flag outdated docs, or suggest a better doc source. Queues locally and points to the matching public GitHub issue template. |
  78. | `resolve_entity` | Map a player, coach, referee, team, competition, season, stage or match to its IDs at every provider through the [Reep register](https://reep.football). Uses a local copy of the free register (`REEP_DUCKDB_PATH`), else the Reep API (`REEP_API_KEY`; keys are issued by hand on request to getintouch+nutmeg@withqwerty.com, with no self-service sign-up), else returns setup steps and a DuckDB query. See [Reep through football-docs](docs/reep/overview.md#using-reep-through-football-docs). |
  79. | `get_metric` | Read a metric card: one checked definition of a football metric with each published variant under its own ID, its formula, source and a checked quote, reference code with test values on open data, and caveats. See [Metric cards](#metric-cards). |
  80. | `list_metrics` | List the metric cards and their variant IDs. |
  81. | `search_papers` | Search scholarly papers on football analytics and sport science in [OpenAlex](https://openalex.org) (title, abstract and full text), [arXiv](https://arxiv.org) and [SportRxiv](https://sportrxiv.org), and, when asked, your Zotero library. See [Papers and web sources](#papers-and-web-sources). |
  82. | `get_paper` | Look up one paper by DOI, arXiv ID, OpenAlex ID or Zotero item: authors, date, venue, all IDs, licence, open copies with their licences, abstract and a citation line. |
  83. | `get_web_source` | Read a public web page or PDF (a blog post, newsletter, club or vendor article, or an author's copy of a paper) as text, with its author, date, licence and Wayback Machine snapshots. Long pages come back by section. |
  84. | `read_paper` | Read a paper: the full text of an open copy, by section, with its licence; or the outline and short passages of a paper you supplied. Kept in your library, so a second read sends no request. |
  85. | `match_quote` | Check that a quote appears in a paper or web page: exact, normalised, close (with a score) or none, with the section, page and a W3C text quote selector. |
  86. | `add_local_paper` | Add a PDF you have to your library, for papers with no open copy. |
  87. | `forget_paper` | Remove one paper from your library. |
  88. | `purge_cache` | Delete your whole paper library (needs `confirm: true`). |
  89. Provider filters use the indexed provider keys shown by `list_providers`, but common aliases are accepted. Examples: `fbref`, `understat`, `ClubElo`, `football-data.co.uk`, and `engsoccerdata` search `free-sources`; `Sofascore` searches `soccerdata`; `ESPN`, `ESPN FC`, and `espn-soccer` search `espn`; `FMDB` searches `fmdb-pro`; `Transfer Room` searches `transferroom`; `Hudl Wyscout` searches `wyscout`; `Stats Perform` / `Opta F24` / `WhoScored` search `opta`; `Metrica`, `Sportec` / `DFL`, and `TRACAB` search `databallpy`; `Second Spectrum` searches `kloppy`; `Hawk-Eye`, `SciSports`, `Signality`, `Respovision`, `GradientSports` and `OptaVision` search `fast-forward`; `unravel` searches `unravelsports`; `SportRadar API` / `Soccer Extended` search `sportradar`; `Sonra` / `Apex` search `statsports`; `Hawkin` searches `hawkin-dynamics`; `ForceDecks` / `NordBord` / `ForceFrame` search `vald`; `The Sports DB` / `TSDB` search `thesportsdb`; `StatsBomb Open Data` searches `statsbomb`.
  90. ## How the index stays current
  91. The package ships a docs index, but doc fixes do not wait for a new package
  92. version. Once a day at most, the server checks the
  93. [`data-latest`](https://github.com/withqwerty/football-docs/releases/tag/data-latest)
  94. release of this repository for a newer index built from `main`:
  95. - It reads a small signed manifest (`manifest-v1-signed.json`) and, only when that
  96. names a newer build, downloads the index (about 6 MB).
  97. - It accepts the manifest only if its ed25519 signature verifies against a public
  98. key shipped in the package (`src/data-signing.ts`). The manifest carries the
  99. index's size and SHA-256, so the signature covers the index too.
  100. - It checks the download's size and SHA-256, its SQLite integrity, its exact
  101. schema and its metadata before using it, and keeps the one it had on any failure.
  102. - It stores downloads in `$XDG_DATA_HOME/football-docs/data/` (by default
  103. `~/.local/share/football-docs/data/`). The next tool call uses the new file; no
  104. restart is needed.
  105. - It runs in the background after start-up and never delays a tool call.
  106. `list_providers` ends with the build time of the index in use and whether it is
  107. bundled or downloaded.
  108. Privacy: the check is one HTTPS request a day to GitHub, plus the download when
  109. there is one. No search queries or other usage data are sent.
  110. Settings, as environment variables in the server's MCP configuration:
  111. - `FOOTBALL_DOCS_DATA=bundled`: use only the index inside the package. No update
  112. check, no downloads. (This does not turn off the paper tools; see
  113. `FOOTBALL_DOCS_PAPERS` under [Papers and web sources](#papers-and-web-sources).)
  114. - `FOOTBALL_DOCS_DATA=auto`: the default for an installed package. Check daily and
  115. use the newest valid index.
  116. - `FOOTBALL_DOCS_DB_PATH=<file>`: use exactly this index file.
  117. - `FOOTBALL_DOCS_DATA_BASE_URL=<url>`: read the manifest and index from a mirror
  118. (HTTPS only).
  119. Offline, or behind a proxy that Node's built-in `fetch` does not use, the check
  120. fails quietly and the server keeps the index it has. Under CI (`CI` set) the check
  121. does not run. A server running from a git checkout defaults to `bundled`, so
  122. development and tests always use the working tree's docs.
  123. ## Papers and web sources
  124. Many football methods come from papers, and some from blog posts: Karun Singh
  125. introduced expected threat (xT) in a blog post, not a paper. `search_papers`
  126. finds papers and the works that cite an idea; a web search finds the original
  127. post, and `get_web_source` reads it. `get_paper` checks that a reference exists,
  128. `read_paper` reads it, and `match_quote` checks that a quote is in the source.
  129. ### Open and paid papers
  130. | Paper | How it gets in | What the tools return |
  131. |---|---|---|
  132. | Open copy: arXiv, an open repository, an open-access publisher, SportRxiv, a public web page | `read_paper` or `get_web_source` finds and reads it | The full text, by section, with its licence |
  133. | A paper you have through a subscription or purchase | You download the PDF and call `add_local_paper`, or keep it in Zotero and use its `zotero:` ID | The outline and passages of at most 200 characters (`FOOTBALL_DOCS_PAPERS_PASSAGE_CHARS`, 50 to 1000) |
  134. football-docs never logs in to a publisher or a library, never holds your
  135. credentials or cookies, and does not use publisher text-mining APIs (their terms
  136. exclude tools like this). When a site answers with a bot check, the tool stops;
  137. download the paper yourself instead.
  138. Zotero: `search_papers` with `sources: ["zotero"]` searches your library, and
  139. `read_paper` reads an item's PDF. Two ways to connect, tried in this order:
  140. 1. Zotero on this computer. In Zotero 7, open Settings > Advanced and turn on
  141. "Allow other applications on this computer to communicate with Zotero". The
  142. tools then use its local API on port 23119; nothing leaves the machine.
  143. 2. The Zotero web API, for when Zotero is not running here (another machine, a
  144. cloud session). Create a read-only key at
  145. [zotero.org/settings/keys](https://www.zotero.org/settings/keys) with access
  146. to your library and its files, and set `ZOTERO_API_KEY` (and optionally
  147. `ZOTERO_USER_ID`; without it the tools ask the key). It reads only files kept
  148. in Zotero's own storage, not linked files; for those it uses Zotero's
  149. full-text index. The key is sent only to api.zotero.org, never to the file
  150. storage host.
  151. An item saved without its PDF (metadata only) is read by its DOI instead, so
  152. `read_paper` still returns the open copy when there is one.
  153. ### Services
  154. The tools call public services at run time. Each reply ends with the services
  155. it asked.
  156. | Service | Used for | Limits |
  157. |---|---|---|
  158. | OpenAlex | Search (title, abstract and full text); DOI and OpenAlex ID lookups; open copies | 1000 credits a day without a key: a search costs 10, a lookup costs nothing. A free key from [openalex.org/settings/api](https://openalex.org/settings/api) raises it. |
  159. | arXiv | Search (title, abstract, authors); arXiv ID lookups with the paper's licence; the paper's HTML or PDF | One request every three seconds to the API; the tool waits its turn. |
  160. | SportRxiv | Search in a local copy of its OAI feed; preprint PDFs | The first search downloads the feed (under 1000 records); after a week, the next search asks only for changes. |
  161. | Crossref | DOI lookups that OpenAlex does not know | |
  162. | Wayback Machine | The earliest and latest snapshot of a web page; the archived copy when the live page fails | The tool never asks it to save a page. |
  163. | The host of an open copy or web page | The text | Bot checks stop the tool. |
  164. ### Your library
  165. - Text the tools read is kept in `$XDG_DATA_HOME/football-docs/papers/` (by
  166. default `~/.local/share/football-docs/papers/`). On macOS and Linux the folder
  167. and its files are readable only by you (modes 0700 and 0600); on Windows they
  168. have the access rules of your user folder. A second read sends no request.
  169. - `forget_paper` removes one paper; `purge_cache` with `confirm: true` deletes
  170. the whole library and the SportRxiv copy. Neither touches your own files or
  171. Zotero.
  172. - Nothing in the library goes into this repository, `data/docs.db` or a data
  173. release. A test fails if a cached paper or any PDF is added to the repository.
  174. - `get_web_source`, `read_paper` and `match_quote` read only public `http` and
  175. `https` addresses. They refuse names that resolve to loopback, private or
  176. link-local addresses, also after a redirect.
  177. - `add_local_paper` reads only PDF files, given by their full path.
  178. ### Settings
  179. As environment variables in the server's MCP configuration:
  180. - `FOOTBALL_DOCS_PAPERS=off`: send no paper or web request, including to the
  181. Zotero web API. Your library, files you add and Zotero on this computer still
  182. work. The provider-doc tools never
  183. call these services.
  184. - `ZOTERO_API_KEY=<key>` and `ZOTERO_USER_ID=<number>`: a read-only Zotero web
  185. API key, for reading Zotero when the app is not running here. The key can also
  186. go in the keychain, as for OpenAlex below.
  187. - `FOOTBALL_DOCS_PAPERS_PASSAGE_CHARS=<n>`: the longest passage returned from a
  188. paper you supplied, 50 to 1000 characters (default 200).
  189. - `OPENALEX_API_KEY=<key>`: your OpenAlex key. On macOS and Linux you can keep it
  190. in the system keychain instead of the environment:
  191. - macOS: `security add-generic-password -s football-docs -a OPENALEX_API_KEY -w <key>`
  192. - Linux (needs `secret-tool`, from libsecret): `secret-tool store --label=football-docs service football-docs key OPENALEX_API_KEY`
  193. - Windows: use the environment variable; the tools do not read Windows Credential Manager.
  194. ## Metric cards
  195. A metric card is one checked definition of a football metric. Many metrics have
  196. several published definitions that give different numbers: on the 2022 World
  197. Cup final, Argentina's PPDA is 7.42 by the StatsBomb/Hudl formula and 9.77 by
  198. Trainor's original. A card lists each definition as a variant with its own ID
  199. (`ppda.statsbomb-hudl`), so an agent can cite exactly which one it used.
  200. Each variant has:
  201. - the definition, formula and zone, in words accurate to the source;
  202. - the source, with one short quote checked by `match_quote` (or in a browser
  203. where the page builds its text with JavaScript) and the date of the check;
  204. - where possible, reference code (`metrics/reference/`), marked exact when it is
  205. the source's own formula on the source's own data and approximation
  206. otherwise, with test values on public open data (StatsBomb open data, at a
  207. pinned commit, downloaded at test time).
  208. Cards so far: `xg`, `npxg`, `xg_assisted` and `xa` (the two metrics called "xA"),
  209. `ppda`, `progressive_passes`, `progressive_carries`, `xt`, `vaep`, `field_tilt`
  210. and `pass_completion`. VAEP's values come from a trained model, so its card has
  211. no reference code or test values; neither do variants that are a provider's
  212. closed model (Opta's xA, for example).
  213. Read a card with `get_metric("ppda")` or one variant with
  214. `get_metric("ppda.statsbomb-hudl")`; `list_metrics` lists them. Cards are also in
  215. `search_docs` under the provider `metric-cards`.
  216. For maintainers: cards are written in `metrics/cards/<id>.toml`.
  217. `python3 scripts/gen_metric_cards.py` builds `metrics/cards.json` (stored in the
  218. index for `get_metric`) and `docs/metric-cards/<id>.md` (for search); CI fails if they
  219. are out of date. `python3 -m pytest metrics/tests` checks every reference
  220. implementation against its card's test values. Before a release, `pnpm
  221. metrics:sources` re-checks every card quote against its live source.
  222. ## Example queries
  223. - "What is Opta qualifier 214?" (big chance)
  224. - "How does StatsBomb represent shot events?"
  225. - "Compare Opta and Wyscout coordinate systems"
  226. - "What player ID fields does Transfermarkt expose?"
  227. - "Does SportMonks have xG data?"
  228. - "What event types does kloppy map to GenericEvent?"
  229. - "How does SPADL represent a tackle?"
  230. - "Who introduced expected threat (xT)? Cite the original." (a web search finds the post, `get_web_source` reads it, `match_quote` checks the quote, `search_papers` finds the papers that cite it)
  231. - "How does VAEP define the value of an action? Quote the paper." (`read_paper` on arXiv 1802.07127, then `match_quote`)
  232. ## Indexed providers
  233. | Provider | Chunks | Categories |
  234. |----------|--------|------------|
  235. | fast-forward | 250 | overview, getting-started, data-model, coordinate-system, orientations, layouts, transformations, distributed-compute, api-reference, 12 provider format pages |
  236. | StatsBomb | 244 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-lineups, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces, data-provenance |
  237. | unravelsports | 202 | overview, installation, quickstart, concepts, graph converters, pressing intensity, formation detection, models, utils, american-football |
  238. | Wyscout | 165 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-analysis-metrics, glossary, identity-surfaces, data-provenance |
  239. | kloppy | 126 | data-model, usage, provider-mapping, tracking-rendering, event-derived-metrics |
  240. | floodlight | 144 | core data objects, io parsers (Tracab, DFL, Kinexon, Opta, SkillCorner, StatsBomb, StatsPerform, Second Spectrum), transforms, metrics, models, visualisation, guides |
  241. | SportMonks | 568 | full v3 endpoint reference (fixtures, livescores, leagues, seasons, states, types, statistics, brackets), syntax and includes, filtering, rate limits, error codes, changelog, plus curated event-types, data-model, api-access, charting-season-stories, identity-surfaces, data-provenance |
  242. | databallpy | 63 | data-model, overview, usage |
  243. | mplsoccer | 65 | overview, pitch-types, visualizations |
  244. | Impect | 79 | overview, data-model, event-types, coordinate-system, concepts, kpi-definitions, identity-surfaces, data-provenance |
  245. | SkillCorner | 52 | api-access, api-endpoints, data-model, physical-data, coordinate-system, concepts, identity-surfaces, data-provenance |
  246. | Free sources | 70 | overview, fbref, understat, football-data-columns, contextual-story-joins, xg-timelines, data-provenance |
  247. | soccerdata | 40 | overview, data-sources, usage |
  248. | TransferRoom | 45 | api-access, api-endpoints, charting-availability, data-model, identity-surfaces, data-provenance |
  249. | Opta | 73 | event-types, qualifiers, coordinate-system, api-access, charting-game-state, charting-lineups, charting-passmaps, charting-set-pieces, charting-shot-placement, identity-surfaces, data-provenance |
  250. | FMDB Pro | 39 | api-access, api-endpoints, data-model, identity-surfaces, data-provenance |
  251. | Sportradar | 481 | integration guide (API basics, coverage tiers, ID handling, match status, update frequencies, push, historical data), Soccer Extended v4 endpoint reference with data-point tables, FAQ, plus curated api-access, api-endpoints, data-model, charting-and-stories, integration-notes, data-provenance |
  252. | socceraction | 34 | SPADL format, VAEP, Expected Threat |
  253. | BeSoccer | 16 | api-access, api-endpoints, data-provenance |
  254. | Driblab | 34 | api-access, api-endpoints, data-model, data-provenance |
  255. | API-Football | 29 | api-access, data-model, identity-surfaces |
  256. | ESPN | 21 | api-access, scoreboard, match-summary, teams-and-standings, identity-and-coverage |
  257. | Reep | 33 | overview, identity-and-ids, download-duckdb-csv, api, data-provenance |
  258. | TheSportsDB | 20 | api-access, api-endpoints, livescore, identity-surfaces, data-provenance |
  259. | FotMob | 5 | identity-surfaces, data-provenance |
  260. | Soccerdonna | 5 | identity-surfaces, data-provenance |
  261. | Transfermarkt | 10 | identity-surfaces, data-provenance, transfermarkt-datasets |
  262. | STATSports | 71 | api-access, api-endpoints, data-model, drill-kpi-metrics (all 319 DrillKpiV7 fields), identity-surfaces, data-provenance |
  263. | Firstbeat | 79 | api-access, api-endpoints, data-model, variables (100 scalars, 17 time series), identity-surfaces, data-provenance |
  264. | Hawkin Dynamics | 69 | api-access, api-endpoints, data-model, test-metrics (535 metrics across 13 test types), identity-surfaces, data-provenance |
  265. | VALD | 318 | api-access, api-endpoints, per-product endpoints and schemas (tenants, profiles, forcedecks, nordbord, forceframe, smartspeed, dynamo, humantrak), identity-surfaces, data-provenance |
  266. | Metric cards | 101 | xg, npxg, xg_assisted, xa, ppda, progressive_passes, progressive_carries, xt, vaep, field_tilt, pass_completion; see [Metric cards](#metric-cards) |
  267. **3,551 searchable chunks** across 32 providers and tools (the metric cards count as one).
  268. STATSports, Firstbeat, Hawkin Dynamics and VALD sell wearables and testing devices.
  269. Their APIs return a customer's own athlete data, which includes personal and health
  270. data. The docs describe the API surface only: endpoints, field names, types and
  271. units as each vendor's public spec or reference page states them. They contain no
  272. athlete data, and none of these vendors' IDs join to a football data provider's IDs.
  273. ESPN coverage consists of curated, dated observations of ESPN-hosted soccer
  274. endpoints, checked for eng.1 and esp.1. These observations are not an official API
  275. contract or an open-data licence. See [ESPN access notes](docs/espn/api-access.md)
  276. for source status and [coverage notes](docs/espn/identity-and-coverage.md) for the
  277. tested requests and limitations.
  278. > **Impect** documentation is built solely from the public
  279. > [ImpectAPI/open-data](https://github.com/ImpectAPI/open-data) repository — a
  280. > static Bundesliga 2023/24 snapshot, representative of Impect's structure and
  281. > metric definitions rather than a complete or current mirror. Impect's
  282. > commercial API is deliberately not documented here. Every enum value, KPI name
  283. > and field name in `docs/impect/` is validated against that repository in CI
  284. > (`pnpm impect:truth`, `src/__tests__/impect-open-data-validation.test.ts`).
  285. > Data source: **Impect**; use is subject to the repository's own Terms of Use.
  286. ## Documentation validation
  287. Docs for AI agents are only useful if they are correct, and prose about an API is
  288. exactly the kind of thing that drifts or gets invented. Where a machine-readable
  289. source of truth exists, this repo checks the docs against it in CI rather than
  290. trusting them.
  291. | Providers | Ground truth | Checked by |
  292. |---|---|---|
  293. | kloppy, socceraction, soccerdata, mplsoccer, floodlight, databallpy, skillcorner, fast-forward, unravelsports | The installed package itself — enum members, importable symbols, class constants, `Literal` parameter vocabularies | `src/__tests__/provider-truth.test.ts` |
  294. | Wyscout, SkillCorner, FMDB Pro, Sportradar | The vendor's own publicly published OpenAPI spec — endpoint paths and methods | `src/__tests__/provider-truth.test.ts` |
  295. | BeSoccer | The vendor's published Postman collection — request vocabulary and parameters | `src/__tests__/provider-truth.test.ts` |
  296. | Driblab | The vendor's published API guide — endpoint paths and methods. Field and group names are not in CI: the guide disagrees with the live API on them, so the docs follow the live API, checked by hand on 2026-09-22 | `src/__tests__/provider-truth.test.ts` |
  297. | Impect | The public [open-data](https://github.com/ImpectAPI/open-data) repository | `src/__tests__/impect-open-data-validation.test.ts` |
  298. | StatsBomb | ID and name pairs observed in a sample of the public [open data](https://github.com/statsbomb/open-data) (three matches per competition-season, at a pinned commit). IDs the sample lacks must be listed in both the Open Data Events specification and kloppy's parser. Regenerate with `pnpm statsbomb:truth` | `src/__tests__/statsbomb-truth.test.ts` |
  299. | Opta | Stats Perform's F24 appendices, which have no machine-readable form. `data/opta-truth.json` holds each ID the docs use, with its label, checked by hand. The test also rejects the wrong meanings earlier docs gave some IDs (`WRONG_MEANINGS` in `src/opta-truth.ts`) | `src/__tests__/opta-truth.test.ts` |
  300. | SportMonks | Type and state IDs as SportMonks publishes them on its definitions pages and in the types spreadsheet linked from its Types page (`data/sportmonks-types-truth.json`, fetched 2026-09-30). Not the full list: the complete one needs an API key | `src/__tests__/sportmonks-truth.test.ts` |
  301. | Reep | The public OpenAPI spec (endpoint paths and methods), and one release's file list, manifest and table columns read from its CSV headers (CSV table list, columns used in the SQL examples, exclusions) | `src/__tests__/provider-truth.test.ts`, `src/__tests__/reep.test.ts` |
  302. | STATSports, Firstbeat, Hawkin Dynamics, VALD | Each vendor's public OpenAPI spec (STATSports v5 to v7, Firstbeat's `openapi.json`, the document inline on Hawkin's API reference page, VALD's eight product specs) — endpoint paths and methods, and every field name in the docs' schema tables. The STATSports `DrillKpiV7` table and the Hawkin metric tables must list the spec's and `metrics.json`'s entries in full. Firstbeat's variable list has no machine-readable source and is copied by hand from its public variables page | `src/__tests__/provider-truth.test.ts`, `src/__tests__/wearable-vendors.test.ts` |
  303. ESPN has a separate observation check in `src/__tests__/espn.test.ts`. It validates
  304. documented endpoint paths, field-table names and types, and source URLs against
  305. `data/espn-observations.json`. These are selected structural observations, not a
  306. published specification. CI reads them offline and does not contact ESPN.
  307. Refresh manually with `python3 scripts/observe_espn.py --scheduled-date YYYYMMDD`,
  308. choosing a future fixture date and using permitted access. The script stores no
  309. raw responses. Review the diff, update the docs and dates, then rebuild the index.
  310. Reep's snapshots age with each download release, which is cut weekly or less often. Run
  311. `python3 scripts/check_reep_live.py` to check every download link and list what
  312. has changed since the snapshots; the refresh steps are in [specs/README.md](specs/README.md#reep).
  313. `pnpm check:upstream` runs every upstream check in one report: pinned package
  314. versions against PyPI, npm and GitHub, each spec snapshot against its public URL,
  315. BeSoccer's and Driblab's truth regenerated from their Postman collection and Notion
  316. page, and the free-source and Reep live checks below. It runs by hand, never in CI, and
  317. lists what to review.
  318. Free sources have no spec, and they tend to fail quietly: a page still answers
  319. 200 after the data has gone. Run `python3 scripts/check_free_sources_live.py` to
  320. request each access path documented in `docs/free-sources/` and check that the
  321. response still carries the data the doc describes. When a doc's access recipe
  322. changes, change its check in the same commit.
  323. Truth files live in `data/provider-truth/` and are generated, not hand-written:
  324. ```bash
  325. pnpm provider:truth # rebuild every package truth file (needs python3.11)
  326. pnpm openapi:truth # rebuild every spec-derived truth file
  327. ```
  328. The specs those derive from are snapshots of **publicly published, unauthenticated**
  329. vendor documentation. Source URLs, fetch dates and refresh instructions are in
  330. [`specs/README.md`](specs/README.md). Wyscout's v3 and v4 specifications merge into
  331. one truth file, because its docs span both. The v2 legacy specification is no
  332. longer mirrored: the docs describe v3 and v4, and no documented fact derives from
  333. the legacy surface.
  334. Each package gets its own pinned venv — co-installing them makes pip silently
  335. downgrade conflicting versions, which would produce truth that disagrees with the
  336. docs. Bump a pin in `scripts/gen_all_truth.sh` and the matching `version` in
  337. `providers.json` together, then re-run and fix whatever the tests flag.
  338. A doc that names an enum member or importable symbol which does not exist in the
  339. real package fails the build. `scripts/gen_openapi_truth.py` derives the same kind
  340. of facts from a vendor OpenAPI spec, for providers documented that way.
  341. Not every vocabulary is an enum. fast-forward's coordinate systems, orientations
  342. and layouts are lowercase strings on `Literal`-annotated parameters, so the truth
  343. files also record what each parameter accepts, and a doc writing
  344. `coordinates="statsbomb"` fails the same way an invented enum member would.
  345. ## Contributing
  346. Contributions are welcome from everyone. There are three ways to help:
  347. 1. **Open an issue** — [request a new provider](https://github.com/withqwerty/football-docs/issues/new/choose), [flag outdated docs](https://github.com/withqwerty/football-docs/issues/new/choose), or [suggest a better doc source](https://github.com/withqwerty/football-docs/issues/new/choose)
  348. 2. **Use the `request_update` tool** — AI agents can flag outdated or missing docs directly via the MCP server, which queues requests locally and points to the matching public GitHub issue template
  349. 3. **Open a PR** — fix errors, add new providers, or improve existing docs
  350. **You don't need to be an expert.** See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
  351. ## For maintainers
  352. ### Crawl pipeline
  353. Provider doc sources are tracked in `providers.json`. The crawl pipeline discovers the best doc source (llms.txt > ReadTheDocs > GitHub README) and writes markdown with provenance frontmatter.
  354. Two registry fields narrow a crawl. `llms_indexes` lists llms.txt files that link to pages rather than contain them; the crawler follows those links (and nested indexes) to each page's markdown copy instead of running discovery. Sportradar uses it for its integration guide and Soccer Extended reference. `exclude_categories` skips whole pages, and `exclude_sections` drops named `##`/`###` sections from pages that are otherwise kept, for content INCLUSION.md keeps out, such as odds. Pages crawled through an index are not byte-for-byte copies: the crawler drops the OpenAPI definition ReadMe appends and SVG diagrams, cuts example payloads over 3 KB with a note, replaces a data-point table repeated from an earlier page with a line naming that page, and marks a split long section "(continued)". It adds no other text.
  355. ```bash
  356. npm run discover # probe sources without crawling
  357. npm run crawl # crawl all providers with sources
  358. npm run crawl -- --provider kloppy # crawl one provider
  359. npm run ingest # rebuild search index from docs/
  360. npm run ingest -- --provider kloppy # re-ingest one provider (incremental)
  361. ```
  362. Each crawled doc carries provenance metadata (source URL, source type, upstream version, crawl timestamp) that is surfaced in search results, so agents can distinguish between curated content and upstream documentation.
  363. ### How doc changes reach users
  364. A merge to `main` that touches `docs/` or `providers.json` runs
  365. `.github/workflows/data.yml`, which rebuilds the index, runs the tests against it,
  366. checks that the **published** server can use it (`scripts/check-data-compat.mjs`),
  367. and publishes it to the `data-latest` release. Installed servers pick it up within
  368. about a day, including servers that have been running for days (they check again
  369. every six hours, at most once a day). Merging a doc PR is therefore also shipping it; there is no later step at
  370. which to stop it. To undo a bad doc change, revert it on `main`, which publishes a
  371. newer build.
  372. **What the signature guarantees.** The publish job signs the manifest with a key
  373. held only in the `data-publish` environment, whose deployment policy allows only
  374. `main`. A manifest that verifies was therefore produced by `data.yml` running on
  375. `main`. Replacing release assets by hand, or from a workflow on another branch,
  376. cannot produce one. It does **not** mean anyone reviewed the change: `main`
  377. accepts a PR with no approvals, so anyone who can merge to `main` can still ship
  378. data. Requiring approvals on `main`, or required reviewers on the `data-publish`
  379. environment (which makes every doc publish wait for a person), would close that
  380. too.
  381. **Rotating the key:** generate a new ed25519 pair, add its public key to
  382. `TRUSTED_KEYS` in `src/data-signing.ts`, release, then replace the
  383. `DATA_SIGNING_KEY` environment secret and `DATA_SIGNING_PUBLIC_KEY` in `data.yml`.
  384. Drop the old key in a later release. A lost private key is handled the same way.
  385. The index carries its own metadata (`meta` table, `src/data-format.ts`): a schema
  386. version, the oldest server version that can read it, the build stamp and the
  387. provider registry. Two rules follow:
  388. - **Changing the schema** (`SCHEMA_SQL`) needs `DATA_SCHEMA_VERSION` raised and an
  389. npm release. Servers read only `manifest-v<their schema>.json`, so older servers
  390. keep their last compatible data rather than breaking.
  391. - **Data that relies on new server code** (for example a new `providers.json` field
  392. the tools must read) needs `MIN_SERVER_VERSION` raised, and that server released
  393. first. Until then the compatibility check fails, and no installed server would
  394. accept the build anyway.
  395. Code changes, including changes to `src/ingest.ts`, still ship only through a
  396. release.
  397. ### Cutting a release
  398. **Pushing the tag is the release.** `.github/workflows/release.yml` runs on any
  399. `v*` tag and does the rest: it re-runs the full check suite, creates the GitHub
  400. Release, and publishes to npm.
  401. Before a release, run `pnpm check:upstream` (see "Documentation validation"). It
  402. reports any provider whose package, spec or live access path has moved since the
  403. docs were written, so a release does not ship docs that are already stale. Fix or
  404. note what it lists; a known, tracked failure (an open issue) need not block.
  405. ```bash
  406. # 1. Bump the version in package.json and server.json (three fields in total).
  407. # Land it on main through a pull request, as `chore: release vX.Y.Z`.
  408. #
  409. # 2. Tag the merge commit and push the tag.
  410. git tag -a v0.11.0 -m "v0.11.0"
  411. git push origin v0.11.0
  412. ```
  413. 3. The release job attaches `site-stats.json` (version, chunk and provider counts,
  414. tools, per-provider chunks; `pnpm site:stats` prints the same) to the GitHub
  415. Release. In nutmeg-site, `pnpm football-docs:release` reads it from the latest
  416. release, rebuilds the football-docs section and saves the announcement card as
  417. `cards/football-docs-v<version>.png`. Update its "What's new" text, then
  418. `pnpm deploy` there.
  419. Release notes come from the body of the `chore: release vX.Y.Z` commit, so write
  420. that message as the release notes you want readers to see. The workflow reads it
  421. from the second parent when the tag sits on a merge commit, strips the commit
  422. trailers, and falls back to GitHub's generated notes if the body is empty.
  423. Three properties worth knowing, because each one exists to stop a specific
  424. failure:
  425. - **The tag must match `package.json`.** A mismatch fails the job before
  426. anything is created or published, so a version can never ship under another
  427. version's name.
  428. - **The full suite runs again.** A tag can be pushed to any commit, including
  429. one that never went through a pull request, so the release path cannot assume
  430. CI already passed on that tree.
  431. - **Re-running is safe.** An existing Release is left alone and an
  432. already-published version is skipped, so a failed job can simply be re-run.
  433. **There is no npm token in this repository.** Publishing uses npm
  434. [trusted publishing](https://docs.npmjs.com/trusted-publishers): the registry
  435. authenticates the workflow itself over OIDC, against a trust configuration on the
  436. package that names this repository and this workflow file. Publishing rights are
  437. bound to `release.yml` rather than to a secret that would work from anywhere it
  438. leaked to, and there is nothing to rotate.
  439. That trust was configured once, with the npm CLI:
  440. ```bash
  441. npm trust github football-docs \
  442. --repo withqwerty/football-docs \
  443. --file release.yml \
  444. --allow-publish
  445. ```
  446. `npm trust list football-docs` shows it; `npm trust revoke` removes it. **Renaming
  447. `release.yml`, or publishing from a different workflow, breaks the match** — by
  448. design. Re-point it with `npm trust github ... --file <new-name>` if the file
  449. ever moves.
  450. Trusted publishing generates [provenance](https://docs.npmjs.com/generating-provenance-statements)
  451. automatically, so the tarball on npm is attested to this repository and this
  452. workflow run without the workflow asking for it.
  453. Two consequences worth knowing:
  454. - **The release job runs on Node 24.** Trusted publishing needs npm >= 11.5.1 and
  455. Node 22 still ships npm 10. Node 24 is in the CI matrix so that a release is
  456. not the first time the suite meets it.
  457. - **The release job does not cache dependencies.** This is the tree that gets
  458. published, so it is resolved fresh from the lockfile rather than rehydrated
  459. from a cache that earlier runs could have poisoned.
  460. Note that `prepublishOnly` runs `pnpm build && pnpm ingest`, which rebuilds
  461. `data/docs.db`. Publishing by hand therefore leaves that file dirty in the
  462. working tree; the content is unchanged, only SQLite's page layout differs, so
  463. `git checkout data/docs.db` clears it.
  464. ## License
  465. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.