Football Data
Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes.
Setup
Before first use, check if the CLI is available:
which sports-skills || pip install sports-skills
If pip install fails (package not found or Python version error), install from GitHub:
pip install git+https://github.com/machina-sports/sports-skills.git
The package requires Python 3.10+. If your default Python is older, use a specific version:
python3 --version
No API keys required.
Quick Start
Prefer the CLI — it avoids Python import path issues:
sports-skills football get_daily_schedule
sports-skills football get_season_standings --season_id=premier-league-2025
Python SDK (alternative):
from sports_skills import football
standings = football.get_season_standings(season_id="premier-league-2025")
schedule = football.get_daily_schedule()
CRITICAL: Before Any Query
CRITICAL: Before calling any data endpoint, verify:
- Season ID is derived from
get_current_season(competition_id="...") — never hardcoded.
- Team ID is verified via
search_team(query="...") if only a name is provided.
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).get_season_leaders and get_missing_players are only called for Premier League seasons (season_id must start with premier-league-).
Choosing the Season
Derive the current year from the system prompt's date (e.g., currentDate: 2026-02-16 → current year is 2026).
- If the user specifies a season, use it as-is.
- 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.
- 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.
- MLS exception: MLS runs spring-fall within a single calendar year. Use
get_current_season(competition_id="mls").
Commands
| Command |
Description |
get_current_season |
Detect current season for a competition |
get_competitions |
List available competitions with current season info |
get_competition_seasons |
Available seasons for a competition |
get_season_schedule |
Full season match schedule |
get_season_standings |
League table for a season |
get_season_leaders |
Top scorers/leaders (Premier League only) |
get_season_teams |
Teams in a season |
search_team |
Search for a team by name |
search_player |
Search for a player by name |
get_team_profile |
Basic team info (no squad/roster) |
get_daily_schedule |
All matches for a date across all leagues |
get_event_summary |
Match summary with scores |
get_event_lineups |
Match lineups |
get_event_statistics |
Match team statistics |
get_event_timeline |
Match timeline (goals, cards, subs) |
get_team_schedule |
Schedule for a specific team |
get_head_to_head |
UNAVAILABLE — returns empty |
get_event_xg |
xG data (top 5 leagues only) |
get_event_players_statistics |
Player-level match stats with optional xG |
get_missing_players |
Injured/doubtful players (Premier League only) |
get_season_transfers |
Transfer history via Transfermarkt |
get_player_season_stats |
Player season stats via ESPN |
get_player_profile |
Player profile (FPL and/or Transfermarkt) |
See references/api-reference.md for full parameter lists, return shapes, and data coverage table.
Examples
Example 1: Premier League table
User says: "Show me the Premier League table"
Actions:
- Call
get_current_season(competition_id="premier-league") to get the current season_id
- Call
get_season_standings(season_id=<season_id from step 1>)
Result: Standings table with position, team, played, won, drawn, lost, GD, points
Example 2: Match report
User says: "How did Arsenal vs Liverpool go?"
Actions:
- Call
get_daily_schedule() or get_team_schedule(team_id="359") to find the event_id
- Call
get_event_summary(event_id="...") for the score
- Call
get_event_statistics(event_id="...") for possession, shots, etc.
- Call
get_event_xg(event_id="...") for xG comparison (EPL — top 5 only)
Result: Match report with scores, key stats, and xG
Example 3: Team deep dive
User says: "Deep dive on Chelsea's recent form"
Actions:
- Call
search_team(query="Chelsea") → team_id=363, competition=premier-league
- Call
get_team_schedule(team_id="363", competition_id="premier-league") → find recent closed events
- For each recent match, call in parallel:
get_event_xg, get_event_statistics, get_event_players_statistics
- Call
get_missing_players(season_id=<season_id>) → filter Chelsea's injured/doubtful players
Result: xG trend across matches, key player stats, and injury report
Example 4: Player market value
User says: "What's Saka's market value?"
Actions:
- Call
get_player_profile(tm_player_id="433177") for Transfermarkt data
- Optionally add
fpl_id for FPL stats
Result: Market value, value history, and transfer history
Example 5: Non-PL club
User says: "Tell me about Corinthians"
Actions:
- Call
search_team(query="Corinthians") → team_id=874, competition=serie-a-brazil
- Call
get_team_schedule(team_id="874", competition_id="serie-a-brazil") for fixtures
- Pick a recent match and call
get_event_timeline(event_id="...") for goals, cards, subs
Result: Fixtures, timeline events (note: xG, FPL stats, and season leaders NOT available for Brazilian Serie A)
Commands that DO NOT exist — never call these
get_standingsget_season_standings (requires season_id).get_live_scoresget_daily_schedule() for today's matches.get_team_squadget_team_rosterget_team_profile does NOT return players. Use get_season_leaders for PL player IDs, then get_player_profile.get_transfersget_season_transfers (requires season_id + tm_player_ids).get_match_resultsget_matchget_event_summary with an event_id.get_player_statsget_event_players_statistics for match-level stats, or get_player_profile for career data.get_scoresget_resultsget_event_summary with an event_id.get_fixturesget_daily_schedule for today's matches or get_season_schedule for a full season.get_league_tableget_season_standings with a season_id.
If a command is not in the Commands table above, it does not exist. Do not try commands not listed.
Error Handling
When a command fails (wrong event_id, missing data, network error, etc.), do not surface the raw error to the user. Instead:
- Catch it silently — treat the failure as an exploratory miss.
- Try alternatives — if an event_id returns no data, call
get_daily_schedule() or get_team_schedule() to discover the correct ID.
- 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?").
Troubleshooting
Error: sports-skills command not found
Cause: Package not installed
Solution: Run pip install sports-skills. If not on PyPI, install from GitHub: pip install git+https://github.com/machina-sports/sports-skills.git
Error: ModuleNotFoundError: No module named 'sports_skills'
Cause: Package not installed or path issue
Solution: Install the package. Prefer the CLI over Python imports to avoid path issues
Error: get_season_leaders or get_missing_players returns empty for a non-PL league
Cause: These commands only work for Premier League; they silently return empty for other leagues
Solution: Check the Data Coverage table in references/api-reference.md. For other leagues, use get_event_players_statistics for player data
Error: get_team_profile returns no players
Cause: This command does not return squad rosters — this is expected behavior
Solution: For PL teams, use get_season_leaders to find player FPL IDs, then get_player_profile(fpl_id="...")
Error: Wrong season_id format
Cause: Season ID must follow the {league-slug}-{year} format
Solution: Use get_current_season(competition_id="...") to discover the correct format. Example: "premier-league-2025", not "2025-2026" or "EPL-2025"
Error: No xG data for a recent match
Cause: Understat data may lag 24-48 hours after a match ends
Solution: If get_event_xg returns empty for a recent top-5 match, retry later. Only available for EPL, La Liga, Bundesliga, Serie A, Ligue 1
Error: Team or event ID unknown
Cause: ID was guessed instead of looked up
Solution: Use search_team(query="team name") to find team IDs, or get_daily_schedule / get_season_schedule to find event IDs. Never guess IDs.
