Football Data

1---2name: football-data3description: |4  Football (soccer) data across 13 leagues — standings, schedules, match stats, xG, transfers, player profiles. Zero config, no API keys. Covers Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Champions League, World Cup, Championship, Eredivisie, Primeira Liga, Serie A Brazil, European Championship.5 6  Use when: user asks about football/soccer standings, fixtures, match stats, xG, lineups, player values, transfers, injury news, league tables, daily fixtures, or player profiles.7  Don't use when: user asks about American football/NFL (use nfl-data), college football (use cfb-data), NBA (use nba-data), WNBA (use wnba-data), college basketball (use cbb-data), NHL (use nhl-data), MLB (use mlb-data), tennis (use tennis-data), golf (use golf-data), Formula 1 (use fastf1), or betting odds (use polymarket or kalshi). Don't use for live/real-time scores — data updates post-match. Don't use get_season_leaders or get_missing_players for non-Premier League leagues (they return empty). Don't use get_event_xg for leagues outside the top 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1).8license: MIT9metadata:10  author: machina-sports11  version: "0.1.0"12---13 14# Football Data15 16Before writing queries, consult `references/api-reference.md` for endpoints, ID conventions, and data shapes.17 18## Setup19 20Before first use, check if the CLI is available:21```bash22which sports-skills || pip install sports-skills23```24If `pip install` fails (package not found or Python version error), install from GitHub:25```bash26pip install git+https://github.com/machina-sports/sports-skills.git27```28The package requires Python 3.10+. If your default Python is older, use a specific version:29```bash30python3 --version  # check version31# If < 3.10, try: python3.12 -m pip install sports-skills32# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills33```34No API keys required.35 36## Quick Start37 38Prefer the CLI — it avoids Python import path issues:39```bash40sports-skills football get_daily_schedule41sports-skills football get_season_standings --season_id=premier-league-202542```43 44Python SDK (alternative):45```python46from sports_skills import football47 48standings = football.get_season_standings(season_id="premier-league-2025")49schedule = football.get_daily_schedule()50```51 52## CRITICAL: Before Any Query53 54CRITICAL: Before calling any data endpoint, verify:55- Season ID is derived from `get_current_season(competition_id="...")` — never hardcoded.56- Team ID is verified via `search_team(query="...")` if only a name is provided.57- `get_event_xg` and `get_event_players_statistics` (with xG) are only called for top-5 leagues (EPL, La Liga, Bundesliga, Serie A, Ligue 1).58- `get_season_leaders` and `get_missing_players` are only called for Premier League seasons (season_id must start with `premier-league-`).59 60## Choosing the Season61 62Derive the current year from the system prompt's date (e.g., `currentDate: 2026-02-16` → current year is 2026).63 64- **If the user specifies a season**, use it as-is.65- **If the user says "current", "latest", or doesn't specify**: Call `get_current_season(competition_id="...")` to get the active season_id. Do NOT guess or hardcode the year.66- **Season format**: Always `{league-slug}-{year}` (e.g., `"premier-league-2025"` for the 2025-26 season). The year is the start year of the season, not the end year.67- **MLS exception**: MLS runs spring-fall within a single calendar year. Use `get_current_season(competition_id="mls")`.68 69## Commands70 71| Command | Description |72|---|---|73| `get_current_season` | Detect current season for a competition |74| `get_competitions` | List available competitions with current season info |75| `get_competition_seasons` | Available seasons for a competition |76| `get_season_schedule` | Full season match schedule |77| `get_season_standings` | League table for a season |78| `get_season_leaders` | Top scorers/leaders (Premier League only) |79| `get_season_teams` | Teams in a season |80| `search_team` | Search for a team by name |81| `search_player` | Search for a player by name |82| `get_team_profile` | Basic team info (no squad/roster) |83| `get_daily_schedule` | All matches for a date across all leagues |84| `get_event_summary` | Match summary with scores |85| `get_event_lineups` | Match lineups |86| `get_event_statistics` | Match team statistics |87| `get_event_timeline` | Match timeline (goals, cards, subs) |88| `get_team_schedule` | Schedule for a specific team |89| `get_head_to_head` | UNAVAILABLE — returns empty |90| `get_event_xg` | xG data (top 5 leagues only) |91| `get_event_players_statistics` | Player-level match stats with optional xG |92| `get_missing_players` | Injured/doubtful players (Premier League only) |93| `get_season_transfers` | Transfer history via Transfermarkt |94| `get_player_season_stats` | Player season stats via ESPN |95| `get_player_profile` | Player profile (FPL and/or Transfermarkt) |96 97See `references/api-reference.md` for full parameter lists, return shapes, and data coverage table.98 99## Examples100 101Example 1: Premier League table102User says: "Show me the Premier League table"103Actions:1041. Call `get_current_season(competition_id="premier-league")` to get the current season_id1052. Call `get_season_standings(season_id=<season_id from step 1>)`106Result: Standings table with position, team, played, won, drawn, lost, GD, points107 108Example 2: Match report109User says: "How did Arsenal vs Liverpool go?"110Actions:1111. Call `get_daily_schedule()` or `get_team_schedule(team_id="359")` to find the event_id1122. Call `get_event_summary(event_id="...")` for the score1133. Call `get_event_statistics(event_id="...")` for possession, shots, etc.1144. Call `get_event_xg(event_id="...")` for xG comparison (EPL — top 5 only)115Result: Match report with scores, key stats, and xG116 117Example 3: Team deep dive118User says: "Deep dive on Chelsea's recent form"119Actions:1201. Call `search_team(query="Chelsea")` → team_id=363, competition=premier-league1212. Call `get_team_schedule(team_id="363", competition_id="premier-league")` → find recent closed events1223. For each recent match, call in parallel: `get_event_xg`, `get_event_statistics`, `get_event_players_statistics`1234. Call `get_missing_players(season_id=<season_id>)` → filter Chelsea's injured/doubtful players124Result: xG trend across matches, key player stats, and injury report125 126Example 4: Player market value127User says: "What's Saka's market value?"128Actions:1291. Call `get_player_profile(tm_player_id="433177")` for Transfermarkt data1302. Optionally add `fpl_id` for FPL stats131Result: Market value, value history, and transfer history132 133Example 5: Non-PL club134User says: "Tell me about Corinthians"135Actions:1361. Call `search_team(query="Corinthians")` → team_id=874, competition=serie-a-brazil1372. Call `get_team_schedule(team_id="874", competition_id="serie-a-brazil")` for fixtures1383. Pick a recent match and call `get_event_timeline(event_id="...")` for goals, cards, subs139Result: Fixtures, timeline events (note: xG, FPL stats, and season leaders NOT available for Brazilian Serie A)140 141## Commands that DO NOT exist — never call these142 143- ~~`get_standings`~~ — the correct command is `get_season_standings` (requires `season_id`).144- ~~`get_live_scores`~~ — not available. Use `get_daily_schedule()` for today's matches.145- ~~`get_team_squad`~~ / ~~`get_team_roster`~~ — `get_team_profile` does NOT return players. Use `get_season_leaders` for PL player IDs, then `get_player_profile`.146- ~~`get_transfers`~~ — the correct command is `get_season_transfers` (requires `season_id` + `tm_player_ids`).147- ~~`get_match_results`~~ / ~~`get_match`~~ — use `get_event_summary` with an `event_id`.148- ~~`get_player_stats`~~ — use `get_event_players_statistics` for match-level stats, or `get_player_profile` for career data.149- ~~`get_scores`~~ / ~~`get_results`~~ — use `get_event_summary` with an `event_id`.150- ~~`get_fixtures`~~ — use `get_daily_schedule` for today's matches or `get_season_schedule` for a full season.151- ~~`get_league_table`~~ — use `get_season_standings` with a `season_id`.152 153If a command is not in the Commands table above, it does not exist. Do not try commands not listed.154 155## Error Handling156 157When a command fails (wrong event_id, missing data, network error, etc.), **do not surface the raw error to the user**. Instead:1581. Catch it silently — treat the failure as an exploratory miss.1592. Try alternatives — if an event_id returns no data, call `get_daily_schedule()` or `get_team_schedule()` to discover the correct ID.1603. Only report failure after exhausting alternatives — use a clean message (e.g., "I couldn't find that match — can you confirm the teams or date?").161 162## Troubleshooting163 164Error: `sports-skills` command not found165Cause: Package not installed166Solution: Run `pip install sports-skills`. If not on PyPI, install from GitHub: `pip install git+https://github.com/machina-sports/sports-skills.git`167 168Error: `ModuleNotFoundError: No module named 'sports_skills'`169Cause: Package not installed or path issue170Solution: Install the package. Prefer the CLI over Python imports to avoid path issues171 172Error: `get_season_leaders` or `get_missing_players` returns empty for a non-PL league173Cause: These commands only work for Premier League; they silently return empty for other leagues174Solution: Check the Data Coverage table in `references/api-reference.md`. For other leagues, use `get_event_players_statistics` for player data175 176Error: `get_team_profile` returns no players177Cause: This command does not return squad rosters — this is expected behavior178Solution: For PL teams, use `get_season_leaders` to find player FPL IDs, then `get_player_profile(fpl_id="...")`179 180Error: Wrong season_id format181Cause: Season ID must follow the `{league-slug}-{year}` format182Solution: Use `get_current_season(competition_id="...")` to discover the correct format. Example: `"premier-league-2025"`, not `"2025-2026"` or `"EPL-2025"`183 184Error: No xG data for a recent match185Cause: Understat data may lag 24-48 hours after a match ends186Solution: If `get_event_xg` returns empty for a recent top-5 match, retry later. Only available for EPL, La Liga, Bundesliga, Serie A, Ligue 1187 188Error: Team or event ID unknown189Cause: ID was guessed instead of looked up190Solution: Use `search_team(query="team name")` to find team IDs, or `get_daily_schedule` / `get_season_schedule` to find event IDs. Never guess IDs.