football-docs 0.1.2 → 0.2.0

package/docs/soccerdata/data-sources.md

@@ -0,0 +1,131 @@
+# soccerdata Data Sources
+
+## FBref (sd.FBref)
+
+Source: fbref.com, powered by StatsBomb/Opta data. HTTP-based, 7-second rate limit enforced. Supports "Big 5 European Leagues Combined" as a virtual league for efficient bulk scraping.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_leagues()` | League metadata | -- | |
+| `read_seasons()` | Available seasons with URLs | -- | Includes round-robin vs elimination format |
+| `read_schedule()` | Match schedule | `[league, season, game]` | Columns: week, date, time, home/away team, home/away xG, score, game_id |
+| `read_team_season_stats(stat_type)` | Aggregated team stats | `[league, season, team]` | |
+| `read_team_match_stats(stat_type)` | Per-match team logs | `[league, season, team, game]` | Optional `team` filter |
+| `read_player_season_stats(stat_type)` | Aggregated player stats | `[league, season, team, player]` | |
+| `read_player_match_stats(stat_type)` | Per-match player stats | `[league, season, game, team, player]` | Optional `match_id` filter |
+| `read_lineup(match_id=None)` | Lineups | `[league, season, game]` | jersey_number, position, minutes_played, is_starter |
+| `read_events(match_id=None)` | In-match events | `[league, season, game]` | Goals, cards, substitutions with timing |
+
+**Team season stat types**: `standard`, `keeper`, `keeper_adv`, `shooting`, `passing`, `passing_types`, `goal_shot_creation`, `defense`, `possession`, `playing_time`, `misc`.
+
+**Team match stat types**: `schedule`, `keeper`, `shooting`, `passing`, `passing_types`, `goal_shot_creation`, `defense`, `possession`, `misc`.
+
+**Player match stat types**: `summary`, `keepers`, `passing`, `passing_types`, `defense`, `possession`, `misc`.
+
+## Understat (sd.Understat)
+
+Source: understat.com. HTTP-based JSON API with initial cookie-setting request. Coverage: Big 5 European leagues only (EPL, La Liga, Serie A, Bundesliga, Ligue 1).
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_leagues()` | League metadata | -- | |
+| `read_seasons()` | Season metadata with URLs | -- | |
+| `read_schedule()` | Match schedule | `[league, season, game]` | Includes home/away xG, goals, team codes |
+| `read_team_match_stats()` | Per-match team stats | `[league, season, game]` | points, expected_points, xG, npxG, PPDA, deep_completions |
+| `read_player_season_stats()` | Player season aggregates | `[league, season, team, player]` | goals, xG, npG, npxG, assists, xA, shots, key_passes, xGChain, xGBuildup |
+| `read_player_match_stats()` | Per-match player stats | `[league, season, game, team, player]` | minutes, goals, shots, xG, xGChain, xGBuildup, assists, xA |
+| `read_shot_events()` | Shot-level data | `[league, season, game, team, player]` | xG, location_x/y, body_part, situation, result |
+
+**Shot event fields**: `body_part` (Right Foot / Left Foot / Other), `situation` (Open Play / From Corner / Set Piece / Direct Freekick), `result` (Goal / Blocked Shot / Saved Shot / Missed Shot / Shot On Post / Own Goal).
+
+## WhoScored (sd.WhoScored)
+
+Source: whoscored.com (Opta event data). Selenium-based, requires Chrome/Chromium. Rate limit: 5s + 0-5s random delay. Constructor: `sd.WhoScored(leagues, seasons, path_to_browser=None, headless=False)`.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_leagues()` | League metadata with region info | -- | |
+| `read_seasons()` | Seasons with region/league/season IDs | -- | |
+| `read_season_stages()` | Stages within seasons | -- | Group stages, knockouts, etc. |
+| `read_schedule()` | Match schedule | `[league, season, game]` | |
+| `read_missing_players()` | Injured/suspended players | `[league, season, game, team, player]` | Includes reason and status |
+| `read_events()` | Detailed Opta event stream | `[league, season, game]` | See output formats below |
+
+**Event output formats** (`output_fmt` parameter):
+- `'events'`: DataFrame with columns: game_id, period, minute, second, expanded_minute, type, outcome_type, team, player, x, y, end_x, end_y, goal_mouth_y/z, blocked_x/y, qualifiers, is_touch, is_shot, is_goal, card_type, related_event_id
+- `'raw'`: Original WhoScored JSON dict
+- `'spadl'`: SPADL format (requires socceraction package)
+- `'atomic-spadl'`: Atomic-SPADL format (requires socceraction package)
+- `'loader'`: Returns socceraction OptaLoader instance
+- `None`: Cache only, no return
+
+## ClubElo (sd.ClubElo)
+
+Source: clubelo.com. HTTP-based CSV API. Does not filter by league (global data). Elo scores available from 1939 (provisional before 1960).
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_by_date(date=None)` | All team Elo ratings for a date | `team` | Columns: rank, country, level, elo, from, to, league |
+| `read_team_history(team)` | Full Elo timeline for one club | `from` (date) | `max_age` parameter controls cache age |
+
+## ESPN (sd.ESPN)
+
+Source: ESPN's public API (site.api.espn.com). HTTP-based JSON API.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_schedule()` | Match schedule | `[league, season, game]` | date, home/away team, game_id |
+| `read_matchsheet()` | Team-level match stats | `[league, season, game, team]` | venue, attendance, capacity, box score stats |
+| `read_lineup()` | Detailed lineups | `[league, season, game, team, player]` | position, formation_place, sub times, per-player stats |
+
+## Sofascore (sd.Sofascore)
+
+Source: sofascore.com API. HTTP-based JSON API.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_leagues()` | League metadata with league_id | -- | |
+| `read_seasons()` | Season metadata with season_id | -- | |
+| `read_league_table()` | Standings | `[league, season]` | MP, W, D, L, GF, GA, GD, Pts |
+| `read_schedule()` | Match schedule | `[league, season, game]` | round, week, date, scores, game_id |
+
+## SoFIFA (sd.SoFIFA)
+
+Source: sofifa.com (FIFA video game ratings). HTTP-based, 1-second rate limit. Uses `versions` parameter instead of seasons -- maps to FIFA game database snapshots. Options: `'latest'` (default), `'all'`, specific version ID, or list of IDs.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_leagues()` | League metadata | -- | |
+| `read_versions()` | Available FIFA editions/updates | -- | version_id for each snapshot |
+| `read_teams()` | Teams per league per version | -- | |
+| `read_players(team=None)` | Player lists with player_id | -- | |
+| `read_team_ratings()` | 23 team attributes | -- | overall, attack, midfield, defence, build_up_speed/dribbling/passing, etc. |
+| `read_player_ratings()` | 36 individual player attributes | -- | overall, potential, crossing, finishing, dribbling, pace, etc. |
+
+**Player rating attributes**: overall, potential, crossing, finishing, heading_accuracy, short_passing, volleys, dribbling, curve, fk_accuracy, long_passing, ball_control, acceleration, sprint_speed, agility, reactions, balance, shot_power, jumping, stamina, strength, long_shots, aggression, interceptions, positioning, vision, penalties, composure, defensive_awareness, standing_tackle, sliding_tackle, GK stats.
+
+## MatchHistory (sd.MatchHistory)
+
+Source: football-data.co.uk. HTTP-based CSV files. Historical match results with extensive betting odds.
+
+**Methods**:
+
+| Method | Returns | Index | Notes |
+|---|---|---|---|
+| `read_games()` | Comprehensive match data | `[league, season, game]` | See columns below |
+
+**Key columns**: league, date, home/away team, referee, full-time/half-time goals, shots, shots on target, fouls, corners, cards, plus betting odds from multiple bookmakers (Bet365, Betway, Pinnacle, etc.). Full column documentation at football-data.co.uk/notes.txt.

package/docs/soccerdata/overview.md

@@ -0,0 +1,54 @@
+# soccerdata
+
+## Overview
+
+soccerdata is a Python library that scrapes football data from popular websites and returns pandas DataFrames with consistent, matching column names and identifiers across datasets. Data is downloaded on demand and cached locally. Licensed under Apache 2.0, authored by Pieter Robberechts (KU Leuven).
+
+- **Install**: `pip install soccerdata` (optional: `pip install soccerdata[socceraction]` for SPADL conversion)
+- **Python**: >=3.9, <3.14
+- **Key dependencies**: pandas, lxml, seleniumbase (Selenium scrapers), tls_requests, html5lib, unidecode
+
+## Supported Sources
+
+| Scraper Class | Source | Access Method | Rate Limit | Coverage |
+|---|---|---|---|---|
+| `sd.FBref` | fbref.com (Opta/StatsBomb data) | HTTP (tls_requests) | 7s between requests | Top leagues + many more, 2017/18+ for detailed stats |
+| `sd.Understat` | understat.com | HTTP (JSON API) | None explicit | Big 5 European leagues only |
+| `sd.WhoScored` | whoscored.com (Opta data) | Selenium (Chrome) | 5s + 0-5s random | Top leagues, detailed event data |
+| `sd.Sofascore` | sofascore.com | HTTP (JSON API) | None explicit | Wide coverage |
+| `sd.ESPN` | ESPN public API | HTTP (JSON API) | None explicit | Top leagues |
+| `sd.ClubElo` | clubelo.com | HTTP (CSV API) | None explicit | All European clubs, 1939-present |
+| `sd.SoFIFA` | sofifa.com (FIFA game ratings) | HTTP | 1s between requests | All FIFA-rated leagues |
+| `sd.MatchHistory` | football-data.co.uk | HTTP (CSV download) | None | 25+ leagues, results + betting odds |
+
+## Built-in League Support
+
+| League ID | FBref | Understat | WhoScored | ESPN | Sofascore | ClubElo | MatchHistory | SoFIFA |
+|---|---|---|---|---|---|---|---|---|
+| ENG-Premier League | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| ESP-La Liga | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| ITA-Serie A | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| GER-Bundesliga | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| FRA-Ligue 1 | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| INT-World Cup | Yes | - | Yes | - | - | - | - | - |
+| INT-European Championship | Yes | - | Yes | - | Yes | - | - | - |
+
+Custom leagues can be added via `~/soccerdata/config/league_dict.json`.
+
+## Architecture
+
+Two base reader classes:
+- **`BaseRequestsReader`** -- uses `tls_requests` (TLS-fingerprint-resistant HTTP client, not standard `requests`). Used by: FBref, Understat, ClubElo, ESPN, Sofascore, SoFIFA, MatchHistory.
+- **`BaseSeleniumReader`** -- uses SeleniumBase with undetected-chromedriver (Chrome). Used by: WhoScored only. Constructor accepts `path_to_browser` and `headless` (default `False`).
+
+Both inherit from abstract `BaseReader` which provides caching, proxy management, league/season selection.
+
+## Limitations and Caveats
+
+- **Web scraping is fragile**: The README warns "any changes to the scraped websites will break the package."
+- **Anti-scraping / IP blocking**: WhoScored uses Incapsula protection (code checks for "Incapsula incident ID"). FBref enforces strict 7s rate limits. All HTTP scrapers use TLS-fingerprint-resistant requests.
+- **WhoScored requires Chrome browser**: Slower, more resource-intensive, harder to run in CI. Headless mode may trigger anti-bot detection.
+- **Limited built-in leagues**: Only 5+3 leagues built-in. Understat only covers Big 5 European leagues.
+- **No authentication required**: All scrapers use public-facing websites/APIs.
+- **FBref multi-level columns**: Returns DataFrames with multi-level column headers (category + stat) that can be tricky to work with.
+- **SoFIFA uses FIFA game versions**, not real-world seasons. The `versions` parameter maps to specific game database snapshots.

package/docs/soccerdata/usage.md

@@ -0,0 +1,157 @@
+# soccerdata Usage Guide
+
+## Installation
+
+```bash
+pip install soccerdata
+
+# With SPADL conversion support (for WhoScored events)
+pip install soccerdata[socceraction]
+```
+
+## Basic Usage Pattern
+
+All scrapers follow the same pattern: instantiate with league(s) and season(s), then call `read_*()` methods to get DataFrames.
+
+```python
+import soccerdata as sd
+
+# Single league, single season
+fbref = sd.FBref('ENG-Premier League', '2023-2024')
+
+# Multiple leagues and seasons
+fbref = sd.FBref(
+    ['ENG-Premier League', 'ESP-La Liga'],
+    ['2022-2023', '2023-2024']
+)
+
+# Fetch data -- returns pandas DataFrames
+schedule = fbref.read_schedule()
+team_stats = fbref.read_team_season_stats(stat_type="passing")
+player_stats = fbref.read_player_season_stats(stat_type="standard")
+```
+
+## Season Format
+
+Very flexible parsing -- all of these are equivalent:
+
+```python
+'2021', '21', '2020-2021', '2020/2021', '2020-21', '20-21', '20/21', 2021
+```
+
+Internally normalised to either single-year or multi-year format depending on league calendar. If no seasons are specified, defaults to the last 5 seasons.
+
+## DataFrame Structure
+
+All data returns as pandas DataFrames with **MultiIndex**. Common index patterns:
+
+| Index Pattern | Used For |
+|---|---|
+| `[league, season, game]` | Match-level data |
+| `[league, season, team]` | Team season aggregates |
+| `[league, season, team, player]` | Player season stats |
+| `[league, season, game, team, player]` | Player match stats |
+
+**Game ID format**: `"YYYY-MM-DD home_team-away_team"` (constructed by `make_game_id()`).
+
+**Column naming**: All columns converted to snake_case. FBref often has multi-level column headers (level 0 = stat category, level 1 = specific stat).
+
+## Team Name Standardization
+
+All scrapers apply `TEAMNAME_REPLACEMENTS` to normalize team names across sources. Add custom mappings in `~/soccerdata/config/teamname_replacements.json`:
+
+```json
+{
+  "StandardName": ["Alternative1", "Alternative2"]
+}
+```
+
+## Caching and Configuration
+
+**Directory structure** (default `~/soccerdata/`):
+- `data/` -- cached data files, subdirectories per source (FBref/, Understat/, etc.)
+- `config/` -- `league_dict.json`, `teamname_replacements.json`
+- `logs/` -- `info.log`, `error.log` (rotating, 1MB max, 10 backups)
+
+**Environment variables**:
+
+| Variable | Description | Default |
+|---|---|---|
+| `SOCCERDATA_DIR` | Base directory | `~/soccerdata` |
+| `SOCCERDATA_NOCACHE` | Disable reading cache (`true`/`1`/`t`) | `false` |
+| `SOCCERDATA_NOSTORE` | Disable writing cache | `false` |
+| `SOCCERDATA_MAXAGE` | Max cache age in days | None (no expiry) |
+| `SOCCERDATA_LOGLEVEL` | Logging level | `INFO` |
+
+**Constructor cache parameters**:
+
+```python
+# Ignore cached data, always re-download
+fbref = sd.FBref('ENG-Premier League', no_cache=True)
+
+# Do not save downloaded data to disk
+fbref = sd.FBref('ENG-Premier League', no_store=True)
+
+# Custom cache directory
+fbref = sd.FBref('ENG-Premier League', data_dir=Path('/tmp/soccerdata'))
+```
+
+For current (incomplete) seasons, cached data is automatically re-fetched. Use `force_cache=True` on read methods to override this and use cached data even for current seasons.
+
+## Proxy Support
+
+```python
+# Tor proxy on default port 9050
+fbref = sd.FBref('ENG-Premier League', proxy='tor')
+
+# Custom SOCKS5 proxy
+fbref = sd.FBref('ENG-Premier League', proxy='socks5://host:port')
+
+# Rotating proxy list
+fbref = sd.FBref('ENG-Premier League', proxy=['proxy1', 'proxy2'])
+
+# Custom callable returning a proxy URL
+fbref = sd.FBref('ENG-Premier League', proxy=my_proxy_function)
+```
+
+## Rate Limits and Retries
+
+| Scraper | Rate Limit | Retry Behaviour |
+|---|---|---|
+| FBref | 7s between requests | Up to 5 retries |
+| WhoScored | 5s + 0-5s random delay | 5 retries with exponential backoff (0s, 10s, 20s, 30s, 40s) |
+| SoFIFA | 1s between requests | Up to 5 retries |
+| Others | No explicit rate limit | Up to 5 retries |
+
+## WhoScored-Specific Setup
+
+WhoScored requires a browser for Selenium-based scraping:
+
+```python
+ws = sd.WhoScored(
+    'ENG-Premier League', '2023-2024',
+    path_to_browser='/usr/bin/chromium',  # optional, auto-detects
+    headless=False  # headless may trigger anti-bot detection
+)
+
+# Get Opta event data
+events = ws.read_events(output_fmt='events')  # DataFrame
+raw = ws.read_events(output_fmt='raw')         # JSON dict
+spadl = ws.read_events(output_fmt='spadl')      # SPADL format (needs socceraction)
+```
+
+## Cross-Source Workflow Example
+
+```python
+import soccerdata as sd
+
+# Combine FBref stats with Understat xG data
+fbref = sd.FBref('ENG-Premier League', '2023-2024')
+understat = sd.Understat('ENG-Premier League', '2023-2024')
+
+# Team names are automatically standardized across sources
+team_stats = fbref.read_team_season_stats(stat_type="standard")
+xg_stats = understat.read_team_match_stats()
+
+# Match on standardized team names in the index
+```

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "football-docs",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Searchable football data provider documentation for AI coding agents. Like Context7 for football data.",
   "type": "module",
   "bin": {
     "football-docs": "bin/serve.js"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsc",
+    "prebuild": "npm run check",
+    "check": "tsc --noEmit",
     "dev": "tsx src/index.ts",
     "ingest": "tsx src/ingest.ts",
-    "start": "node dist/index.js"
+    "crawl": "tsx src/crawl.ts",
+    "discover": "tsx src/crawl.ts --discover",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "prepublishOnly": "npm run build && npm run ingest",
+    "start": "node dist/index.js",
+    "test": "vitest run"
   },
   "keywords": [
     "football",
@@ -34,19 +45,27 @@
     "url": "git+https://github.com/withqwerty/football-docs.git"
   },
   "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "better-sqlite3": "^11.9.1"
+    "@mozilla/readability": "^0.6.0",
+    "better-sqlite3": "^11.9.1",
+    "linkedom": "^0.18.12",
+    "turndown": "^7.2.2"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.2",
+    "@types/turndown": "^5.0.6",
     "tsx": "^4.19.4",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.2"
   },
   "files": [
     "dist/",
     "bin/",
     "data/docs.db",
-    "docs/"
+    "docs/",
+    "providers.json"
   ]
 }

package/providers.json

@@ -0,0 +1,170 @@
+{
+  "$comment": [
+    "Football Docs Provider Registry",
+    "",
+    "Source types:",
+    "  llms_txt     - llms.txt or llms-full.txt (purpose-built for LLMs, highest priority)",
+    "  readthedocs  - ReadTheDocs site (structured, version-pinned)",
+    "  github_docs  - GitHub repo docs/ folder or README",
+    "  api_docs     - Standalone API documentation site",
+    "  curated      - Hand-written by football-docs contributors",
+    "",
+    "To add a new provider: add an entry here, then run: npm run crawl -- --provider <name>"
+  ],
+  "providers": {
+    "statsbomb": {
+      "description": "Event data provider with free open-data repository",
+      "version": null,
+      "package": { "type": "github", "repo": "statsbomb/open-data" },
+      "sources": [
+        { "url": "https://github.com/statsbomb/open-data", "type": "github_docs" },
+        { "type": "curated", "note": "Cross-provider comparisons, coordinate conversion formulas" }
+      ],
+      "last_crawled": null
+    },
+    "opta": {
+      "description": "Stats Perform event data (F24/F7 XML format)",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "No public docs available; compiled from community knowledge" }
+      ],
+      "last_crawled": null
+    },
+    "wyscout": {
+      "description": "Hudl/Wyscout event and match data",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Compiled from API documentation and community knowledge" }
+      ],
+      "last_crawled": null
+    },
+    "sportmonks": {
+      "description": "REST API for football fixtures, standings, and events",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "url": "https://docs.sportmonks.com/football", "type": "api_docs" },
+        { "type": "curated", "note": "Event type mappings and field descriptions" }
+      ],
+      "last_crawled": null
+    },
+    "kloppy": {
+      "description": "Python library for standardising football data across providers",
+      "version": "3.16.0",
+      "package": { "type": "pypi", "name": "kloppy" },
+      "sources": [
+        { "url": "https://kloppy.pysport.org/", "type": "readthedocs" },
+        { "url": "https://github.com/PySport/kloppy", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "socceraction": {
+      "description": "Python library for SPADL representation and VAEP/xT action valuation",
+      "version": "1.5.3",
+      "package": { "type": "pypi", "name": "socceraction" },
+      "sources": [
+        { "url": "https://socceraction.readthedocs.io/en/latest/", "type": "readthedocs" },
+        { "url": "https://github.com/ML-KULeuven/socceraction", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "soccerdata": {
+      "description": "Python library for scraping football data from popular websites",
+      "version": "1.8.8",
+      "package": { "type": "pypi", "name": "soccerdata" },
+      "sources": [
+        { "url": "https://soccerdata.readthedocs.io/en/latest/", "type": "readthedocs" },
+        { "url": "https://github.com/probberechts/soccerdata", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "mplsoccer": {
+      "description": "Python library for drawing soccer pitches and visualisations with matplotlib",
+      "version": "1.6.1",
+      "package": { "type": "pypi", "name": "mplsoccer" },
+      "sources": [
+        { "url": "https://mplsoccer.readthedocs.io/en/latest/", "type": "readthedocs" },
+        { "url": "https://github.com/andrewRowlinson/mplsoccer", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "databallpy": {
+      "description": "Python library for loading, synchronising, and analysing tracking and event data",
+      "version": "0.7.2",
+      "package": { "type": "pypi", "name": "databallpy" },
+      "sources": [
+        { "url": "https://databallpy.readthedocs.io/en/latest/", "type": "readthedocs" },
+        { "url": "https://github.com/Alek050/databallpy", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "api-football": {
+      "description": "REST API for football data via RapidAPI (fixtures, standings, players, live scores)",
+      "version": "3",
+      "package": null,
+      "sources": [
+        { "url": "https://www.api-football.com/documentation-v3", "type": "api_docs" }
+      ],
+      "last_crawled": null
+    },
+    "football-data-org": {
+      "description": "REST API for football competition data (v4) — fixtures, standings, teams, players",
+      "version": "4",
+      "package": null,
+      "sources": [
+        { "url": "https://docs.football-data.org/general/v4/index.html", "type": "api_docs" }
+      ],
+      "last_crawled": null
+    },
+    "fpl": {
+      "description": "Fantasy Premier League unofficial API — player stats, fixtures, gameweeks, transfers",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Unofficial undocumented API; compiled from community sources" }
+      ],
+      "last_crawled": null
+    },
+    "floodlight": {
+      "description": "Python library for spatial football data analysis (tracking, pitch control, metrics)",
+      "version": null,
+      "package": { "type": "pypi", "name": "floodlight" },
+      "sources": [
+        { "url": "https://floodlight.readthedocs.io/en/latest/", "type": "readthedocs" },
+        { "url": "https://github.com/floodlight-sports/floodlight", "type": "github_docs" }
+      ],
+      "last_crawled": null
+    },
+    "thesportsdb-v1": {
+      "description": "TheSportsDB v1 API — free tier, search-based endpoints for teams, players, events, livescores",
+      "version": "1",
+      "package": null,
+      "sources": [
+        { "url": "https://www.thesportsdb.com/api/spec/v1/openapi.yaml", "type": "openapi" },
+        { "url": "https://www.thesportsdb.com/documentation", "type": "api_docs" }
+      ],
+      "last_crawled": null
+    },
+    "thesportsdb-v2": {
+      "description": "TheSportsDB v2 API — paid tier, expanded endpoints with schedules, statistics, lookups",
+      "version": "2",
+      "package": null,
+      "sources": [
+        { "url": "https://www.thesportsdb.com/api/spec/v2/openapi.yaml", "type": "openapi" },
+        { "url": "https://www.thesportsdb.com/documentation", "type": "api_docs" }
+      ],
+      "last_crawled": null
+    },
+    "free-sources": {
+      "description": "Free football data sources (FBref, Understat, ClubElo, football-data.co.uk)",
+      "version": null,
+      "package": null,
+      "sources": [
+        { "type": "curated", "note": "Overview and access patterns for free data sources" }
+      ],
+      "last_crawled": null
+    }
+  }
+}