Football Data

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  # 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

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

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: 1. Call get_current_season(competition_id="premier-league") to get the current season_id 2. 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: 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) Result: Match report with scores, key stats, and xG

Example 3: Team deep dive User says: "Deep dive on Chelsea's recent form" Actions: 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, get_event_statistics, get_event_players_statistics 4. 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: 1. Call get_player_profile(tm_player_id="433177") for Transfermarkt data 2. 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: 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 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_standings~~ — the correct command is get_season_standings (requires season_id).
• ~~get_live_scores~~ — not available. Use get_daily_schedule() for today's matches.
• ~~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.
• ~~get_transfers~~ — the correct command is get_season_transfers (requires season_id + tm_player_ids).
• ~~get_match_results~~ / ~~get_match~~ — use get_event_summary with an event_id.
• ~~get_player_stats~~ — use get_event_players_statistics for match-level stats, or get_player_profile for career data.
• ~~get_scores~~ / ~~get_results~~ — use get_event_summary with an event_id.
• ~~get_fixtures~~ — use get_daily_schedule for today's matches or get_season_schedule for a full season.
• ~~get_league_table~~ — use get_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: 1. Catch it silently — treat the failure as an exploratory miss. 2. Try alternatives — if an event_id returns no data, call get_daily_schedule() or get_team_schedule() to discover the correct ID. 3. 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.

Football Data — API Reference

ID Conventions

• season_id: {league-slug}-{year} e.g. "premier-league-2025", "la-liga-2025" (year = start year of the season)
• competition_id: league slug e.g. "premier-league", "serie-a", "champions-league"
• team_id: ESPN team ID (numeric string) e.g. "359" (Arsenal), "86" (Real Madrid)
• event_id: ESPN event ID (numeric string) e.g. "740847"
• fpl_id: FPL element ID or code (PL players only)
• tm_player_id: Transfermarkt player ID e.g. "433177" (Saka), "342229" (Mbappe)

Data Coverage by League

Top 5 leagues (Understat): EPL, La Liga, Bundesliga, Serie A, Ligue 1. PL only (FPL): Premier League — injury news, player stats, ownership, ICT index. All leagues: via ESPN — scores, standings, schedules, match summaries, lineups, team stats.

Data Sources

Commands (Detailed)

get_current_season

Detect current season for a competition. Works for all leagues.

• competition_id (str, required): Competition slug

Returns data.competition and data.season:

{"competition": {"id": "premier-league"}, "season": {"id": "premier-league-2025", "year": "2025"}}

get_competitions

List available competitions with current season info. No params. Works for all leagues.

Returns data.competitions[] with id, name, code, current_season.

get_competition_seasons

Get available seasons for a competition.

• competition_id (str, required): Competition slug

get_season_schedule

Get full season match schedule.

• season_id (str, required): Season slug

Returns data.schedules[].

get_season_standings

Get league table for a season.

• season_id (str, required): Season slug

Returns data.standings[].entries[]:

{
  "position": 1,
  "team": {"id": "359", "name": "Arsenal", "abbreviation": "ARS"},
  "played": 26, "won": 17, "drawn": 6, "lost": 3,
  "goals_for": 50, "goals_against": 18, "goal_difference": 32, "points": 57
}

get_season_leaders

Get top scorers/leaders for a season. Premier League only (via FPL).

• season_id (str, required): Season slug (must be premier-league-*)

Returns data.leaders[] with nested player.name, team.name, goals, assists, played_matches.

get_season_teams

Get teams in a season.

• season_id (str, required): Season slug

search_team

Search for a team by name across all leagues. Uses fuzzy matching.

• query (str, required): Team name
• competition_id (str, optional): Limit to one league

Returns data.results[] with team, competition, season for each match.

search_player

Search for a football player by name.

• query (str, required): Player name

Returns data.results[] with tm_player_id, espn_id, name, team, competition.

get_team_profile

Get basic team info (name, crest, venue). Does NOT return squad.

• team_id (str, required): ESPN team ID
• league_slug (str, optional): League hint

get_daily_schedule

Get all matches for a specific date across all leagues.

• date (str, optional): YYYY-MM-DD. Defaults to today.

Returns data.date and data.events[]:

{
  "id": "748381", "status": "not_started", "start_time": "2026-02-16T20:00Z",
  "competition": {"id": "la-liga"}, "season": {"id": "la-liga-2025"},
  "competitors": [
    {"team": {"id": "9812", "name": "Girona", "abbreviation": "GIR"}, "qualifier": "home", "score": 0},
    {"team": {"id": "83", "name": "Barcelona", "abbreviation": "BAR"}, "qualifier": "away", "score": 0}
  ]
}

Status values: "not_started", "live", "halftime", "closed", "postponed".

get_event_summary

Get match summary with scores.

• event_id (str, required): Match/event ID

get_event_lineups

Get match lineups.

• event_id (str, required): Match/event ID

Returns data.lineups[] with team, formation, starting players, and bench.

get_event_statistics

Get match team statistics.

• event_id (str, required): Match/event ID

Returns data.teams[] with ball_possession, shots_total, shots_on_target, fouls, corners.

get_event_timeline

Get match timeline/key events (goals, cards, substitutions).

• event_id (str, required): Match/event ID

get_team_schedule

Get schedule for a specific team (past results + upcoming fixtures).

• team_id (str, required): ESPN team ID
• league_slug (str, optional): League hint
• season_year (str, optional): Season year filter
• competition_id (str, optional): Filter to a single competition

get_head_to_head

UNAVAILABLE — requires licensed data. Do not call; returns empty results.

• team_id (str, required): First team ID
• team_id_2 (str, required): Second team ID

Alternative: Use get_team_schedule for both teams and filter overlapping matches manually.

get_event_xg

Get expected goals (xG) from Understat. Top 5 leagues only.

• event_id (str, required): Match/event ID

Returns data.teams[] with xg and data.shots[] per shot. May lag 24-48h after a match.

get_event_players_statistics

Get player-level match statistics with optional xG enrichment.

• event_id (str, required): Match/event ID

Returns data.teams[].players[] with statistics including xg and xa (top 5 leagues only).

get_missing_players

Get injured/missing/doubtful players. Premier League only (via FPL).

• season_id (str, required): Season slug (must be premier-league-*)

Returns data.teams[].players[] with status (injured/unavailable/doubtful/suspended), news, chance of playing.

get_season_transfers

Get transfer history for specific players via Transfermarkt.

• season_id (str, required): Season slug
• tm_player_ids (list, required): Transfermarkt player IDs

get_player_season_stats

Get player season stats via ESPN.

• player_id (str, required): ESPN athlete ID
• league_slug (str, optional): League slug hint

get_player_profile

Get player profile via FPL and/or Transfermarkt.

• fpl_id (str, optional): FPL player ID (PL players only)
• tm_player_id (str, optional): Transfermarkt player ID (any league)

Returns market value, value history, transfer history. With fpl_id, also returns FPL stats.

Supported Leagues

Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Championship, Eredivisie, Primeira Liga, Serie A Brazil, Champions League, European Championship, World Cup.

Football Data — Valid Commands & Common Mistakes

Valid Commands

These are the ONLY valid commands. Do not invent or guess command names:

• get_current_season
• get_competitions
• get_competition_seasons
• get_season_schedule
• get_season_standings
• get_season_leaders
• get_season_teams
• search_team
• get_team_profile
• get_daily_schedule
• get_event_summary
• get_event_lineups
• get_event_statistics
• get_event_timeline
• get_team_schedule
• get_head_to_head
• get_event_xg
• get_event_players_statistics
• get_missing_players
• get_season_transfers
• get_player_profile

Commands That DO NOT Exist (Commonly Hallucinated)

• ~~get_standings~~ — the correct command is get_season_standings (requires season_id).
• ~~get_live_scores~~ — not available. Use get_daily_schedule() for today's matches; status field shows "live" for in-progress games.
• ~~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 for individual data.
• ~~get_transfers~~ — the correct command is get_season_transfers (requires season_id + tm_player_ids).
• ~~get_match_results~~ / ~~get_match~~ — use get_event_summary with an event_id.
• ~~get_player_stats~~ — use get_event_players_statistics for match-level stats, or get_player_profile for career data.

Other Common Mistakes

• Using get_season_leaders or get_missing_players on non-PL leagues — they return empty. Check the Data Coverage table.
• Using get_event_xg on leagues outside the top 5 — returns empty. Only works for EPL, La Liga, Bundesliga, Serie A, Ligue 1.
• Guessing team_id or event_id instead of discovering them via search_team, get_daily_schedule, or get_season_schedule.

If you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.

Command Parameter Reference

get_current_season

• competition_id (str, required): Competition slug

get_competitions

No parameters.

get_competition_seasons

• competition_id (str, required): Competition slug

get_season_schedule

• season_id (str, required): Season slug (e.g., "premier-league-2025")

get_season_standings

• season_id (str, required): Season slug

get_season_leaders

• season_id (str, required): Season slug (must be premier-league-*)

get_season_teams

• season_id (str, required): Season slug

search_team

• query (str, required): Team name to search
• competition_id (str, optional): Limit search to one league

get_team_profile

• team_id (str, required): ESPN team ID
• league_slug (str, optional): League hint

get_daily_schedule

• date (str, optional): Date in YYYY-MM-DD format. Defaults to today.

get_event_summary

• event_id (str, required): Match/event ID

get_event_lineups

• event_id (str, required): Match/event ID

get_event_statistics

• event_id (str, required): Match/event ID

get_event_timeline

• event_id (str, required): Match/event ID

get_team_schedule

• team_id (str, required): ESPN team ID
• league_slug (str, optional): League hint
• season_year (str, optional): Season year filter
• competition_id (str, optional): Filter to a single competition

get_head_to_head

UNAVAILABLE — requires licensed data. Do not call this command.

• team_id (str, required): First team ID
• team_id_2 (str, required): Second team ID

get_event_xg

• event_id (str, required): Match/event ID. Top 5 leagues only.

get_event_players_statistics

• event_id (str, required): Match/event ID

get_missing_players

• season_id (str, required): Season slug (must be premier-league-*)

get_season_transfers

• season_id (str, required): Season slug
• tm_player_ids (list, required): Transfermarkt player IDs

get_player_profile

• fpl_id (str, optional): FPL player ID (PL players only)
• tm_player_id (str, optional): Transfermarkt player ID (any league)

At least one ID required.

Football Data — Data Coverage by League

Coverage Table

Not all data is available for every league. Use the right command for the right league.

Top 5 leagues (Understat): EPL, La Liga, Bundesliga, Serie A, Ligue 1. PL only (FPL): Premier League — injury news, player stats, ownership, ICT index. All leagues: via ESPN — scores, standings, schedules, match summaries, lineups, team stats. Transfermarkt: Works for any player with a tm_player_id — market values and transfer history.

Note: MLS uses a different season structure (spring-fall calendar). Use get_current_season(competition_id="mls") to detect the right season_id.

Data Sources

For licensed data with full coverage across all sports (Sportradar, Opta, Genius Sports), see Machina Sports.

Football Data — JSON Schemas

get_current_season

Returns data.competition and data.season:

{"competition": {"id": "premier-league", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "year": "2025"}}

get_season_standings

Returns data.standings[].entries[]:

{
  "position": 1,
  "team": {"id": "359", "name": "Arsenal", "short_name": "Arsenal", "abbreviation": "ARS", "crest": "https://..."},
  "played": 26, "won": 17, "drawn": 6, "lost": 3,
  "goals_for": 50, "goals_against": 18, "goal_difference": 32, "points": 57
}

get_season_leaders

Returns data.leaders[] — note: player name is nested under .player.name:

{
  "player": {"id": "223094", "name": "Erling Haaland", "first_name": "Erling", "last_name": "Haaland", "position": "Forward"},
  "team": {"id": "43", "name": "Man City"},
  "goals": 22, "assists": 6, "penalties": 0, "played_matches": 25
}

Returns empty for non-PL leagues.

get_daily_schedule

Returns data.date and data.events[]:

{
  "id": "748381", "status": "not_started", "start_time": "2026-02-16T20:00Z",
  "competition": {"id": "la-liga", "name": "La Liga"},
  "season": {"id": "la-liga-2025", "year": "2025"},
  "venue": {"name": "Estadi Montilivi", "city": "Girona"},
  "competitors": [
    {"team": {"id": "9812", "name": "Girona", "abbreviation": "GIR"}, "qualifier": "home", "score": 0},
    {"team": {"id": "83", "name": "Barcelona", "abbreviation": "BAR"}, "qualifier": "away", "score": 0}
  ],
  "scores": {"home": 0, "away": 0}
}

Status values: "not_started", "live", "halftime", "closed", "postponed".

get_event_lineups

Returns data.lineups[]:

{
  "team": {"id": "364", "name": "Liverpool", "abbreviation": "LIV"},
  "qualifier": "home",
  "formation": "4-3-3",
  "starting": [{"id": "275599", "name": "Caoimhin Kelleher", "position": "Goalkeeper", "shirt_number": 1}],
  "bench": [{"id": "...", "name": "...", "position": "...", "shirt_number": 62}]
}

get_event_statistics

Returns data.teams[]:

{
  "team": {"id": "244", "name": "Brentford"},
  "qualifier": "home",
  "statistics": {"ball_possession": "40.8", "shots_total": "10", "shots_on_target": "3", "fouls": "12", "corners": "4"}
}

get_event_xg

Returns data.teams[] and data.shots[]:

{"team": {"id": "244", "name": "Brentford"}, "qualifier": "home", "xg": 1.812}

data.shots[] contains individual shot data with xG per shot. Note: very recent matches (last 24-48h) may not be indexed on Understat yet.

get_event_players_statistics

Returns data.teams[].players[]:

{
  "id": "...", "name": "Bukayo Saka", "position": "Midfielder", "shirt_number": 7, "starter": true,
  "statistics": {"appearances": "1", "shotsTotal": "3", "shotsOnTarget": "1", "foulsCommitted": "1", "xg": "0.45", "xa": "0.12"}
}

xg and xa fields only present for top 5 leagues.

get_missing_players

Returns data.teams[].players[]:

{
  "id": "463748", "name": "Mikel Merino Zazon", "web_name": "Merino",
  "position": "Midfielder", "status": "injured",
  "news": "Foot injury - Unknown return date",
  "chance_of_playing_this_round": 0, "chance_of_playing_next_round": 0
}

Status values: "injured", "unavailable", "doubtful", "suspended".

get_season_transfers

Returns data.transfers[]:

{
  "player_tm_id": "433177", "date": "2019-07-01", "season": "19/20",
  "from_team": {"name": "Arsenal U23", "image": "https://..."},
  "to_team": {"name": "Arsenal", "image": "https://..."},
  "fee": "-", "market_value": "-"
}

get_player_profile

With tm_player_id, returns data.player with:

{
  "market_value": {"value": 130000000, "currency": "EUR", "formatted": "EUR130.00m", "date": "09/12/2025", "age": "24", "club": "Arsenal FC"},
  "market_value_history": [{"value": 7000000, "formatted": "EUR7.00m", "date": "23/09/2019", "club": "Arsenal FC"}],
  "transfer_history": [
    {"player_tm_id": "433177", "date": "2019-07-01", "season": "19/20", "from_team": {"name": "Arsenal U23"}, "to_team": {"name": "Arsenal"}, "fee": "-"}
  ]
}

With fpl_id, also includes data.player.fpl_data with FPL stats (points, form, ICT index, ownership, etc.).

search_team

Returns data.results[] with team, competition, and season for each match:

{"team": {"id": "874", "name": "Corinthians"}, "competition": {"id": "serie-a-brazil", "name": "Serie A Brazil"}, "season": {"id": "serie-a-brazil-2025", "year": "2025"}}