Football Data
by @antonelli182
Football (soccer) data across 13 leagues — standings, schedules, match stats, xG, transfers, player profiles. Zero config, no API keys. Covers Premier League...
User: "Show me the Premier League table"
1. Call get_current_season(competition_id="premier-league") to get the current season_id
2. Call get_season_standings(season_id=
3. Present standings table with position, team, played, won, drawn, lost, GD, points
User: "How did Arsenal vs Liverpool go?"
1. Call get_daily_schedule() or get_team_schedule(team_id="359") to find the event_id
2. Call get_event_summary(event_id="...") for the score
3. Call get_event_statistics(event_id="...") for possession, shots, etc.
4. Call get_event_xg(event_id="...") for xG comparison (EPL — top 5 only)
5. Present match report with scores, key stats, and xG
User: "Deep dive on Chelsea's recent form"
1. Call search_team(query="Chelsea") → team_id=363, competition=premier-league
2. Call get_team_schedule(team_id="363", competition_id="premier-league") → find recent closed events
3. For each recent match, call in parallel:
- get_event_xg(event_id="...") for xG comparison and shot map
- get_event_statistics(event_id="...") for possession, shots, passes
- get_event_players_statistics(event_id="...") for individual player xG/xA
4. Call get_missing_players(season_id= → filter Chelsea's injured/doubtful players
5. Call get_season_leaders(season_id= → filter Chelsea players, get their FPL IDs
6. Call get_player_profile(fpl_id="...", tm_player_id="...") for key players — combine FPL stats (form, ownership, ICT) with Transfermarkt data (market value, transfer history)
7. Present: xG trend across matches, key player stats, injury report, market values
User: "What's Saka's market value?"
1. Call get_player_profile(tm_player_id="433177") for Transfermarkt data
2. Optionally add fpl_id for FPL stats if Premier League player
3. Present market value, value history, and transfer history
User: "Tell me about Corinthians"
1. Call search_team(query="Corinthians") → team_id=874, competition=serie-a-brazil
2. Call get_team_schedule(team_id="874", competition_id="serie-a-brazil") for fixtures
3. Pick a recent match and call get_event_timeline(event_id="...") for goals, cards, subs
4. Note: xG, FPL stats, and season leaders are NOT available for Brazilian Serie A
Before first use, check if the CLI is available:
which sports-skills || pip install sports-skills
pip install fails (package not found or Python version error), install from GitHub:
pip install git+https://github.com/machina-sports/sports-skills.git
python3 --version # check version
If < 3.10, try: python3.12 -m pip install sports-skills
On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills
sports-skills command not found: Package not installed. Run pip install sports-skills. If the package is not found on PyPI, install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git. Requires Python 3.10+ — see Setup section.ModuleNotFoundError: No module named 'sports_skills': Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.get_season_leaders and get_missing_players only return data for Premier League. They silently return empty for other leagues — check the Data Coverage table.get_team_profile returns empty players: This is expected — squad rosters are not available. To get player data for a PL team, use get_season_leaders to find players and their FPL IDs, then get_player_profile(fpl_id="...") for detailed stats. For Transfermarkt data, you need the player's tm_player_id.get_season_leaders(season_id="premier-league-2025") to discover FPL IDs for PL players. Transfermarkt IDs must be looked up on transfermarkt.com — the ID is the number at the end of the player's URL. Well-known examples: Cole Palmer = 568177, Bukayo Saka = 433177, Mbappe = 342229.get_event_xg returns empty for a recent top-5 match, try again later.{league-slug}-{year} e.g. "premier-league-2025". Not "2025-2026", not "EPL-2025". Use get_current_season() to discover the correct format.search_team(query="team name") to find team IDs by name, or get_season_teams to list all teams in a season. Use get_daily_schedule or get_season_schedule to find event IDs. IDs are ESPN numeric strings.clawhub install football-data