Football Data

Before writing queries, consult

references/api-reference.md

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If

pip install

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

• 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

get_current_season

get_competitions

get_competition_seasons

get_season_schedule

get_season_standings

get_season_leaders

get_season_teams

search_team

search_player

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_season_stats

get_player_profile

See

references/api-reference.md

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

pip install sports-skills

pip install git+https://github.com/machina-sports/sports-skills.git

Error:

ModuleNotFoundError: No module named 'sports_skills'

Error:

get_season_leaders

get_missing_players

references/api-reference.md

get_event_players_statistics

Error:

get_team_profile

get_season_leaders

get_player_profile(fpl_id="...")

Error: Wrong season_id format Cause: Season ID must follow the

{league-slug}-{year}

get_current_season(competition_id="...")

"premier-league-2025"

"2025-2026"

"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

Error: Team or event ID unknown Cause: ID was guessed instead of looked up Solution: Use

search_team(query="team name")

get_daily_schedule

get_season_schedule