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 resolved via search_team(query="...") and passed as the numeric team_id. For get_head_to_head, get_team_strength, and get_match_forecast, always pass IDs — ambiguous names (e.g. two "Paris" clubs) can resolve to the wrong team.
• The endpoint actually covers the league in question — see the Coverage & Source Map below. Coverage is uneven across sources; an uncovered call returns an empty payload with a message, not data.
• 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").

Coverage & Source Map

This skill stitches several free sources together. Coverage is not uniform — each endpoint works only where its underlying source has data. Check this before promising an answer; when an endpoint isn't covered, it returns an empty payload with an explanatory message (never an error) — read that message and fall back.

Rule of thumb: ESPN answers "what happened" everywhere; the enrichment sources ( Understat/FPL/ClubElo/football-data.co.uk ) add depth only in their coverage zone. ESPN is always the fixture/score authority — never let an enrichment source override an ESPN score.

Gotchas (from live testing)

• `get_team_profile` returns the squad. data.players[] carries the current roster with ESPN athlete ids, shirt numbers and ages — use it instead of collecting names match by match.
• `get_player_season_stats` takes the same league slug as everything else (serie-a-brazil, not only ESPN's bra.1), and its gamelog is the last ~5 matches across competitions, not a season total.
• Scored penalties are `penalty_goal` in the timeline. Count goal + penalty_goal + own_goal when reconciling with the score.
• Pass IDs, not ambiguous names. For H2H/strength/forecast, resolve teams with search_team first and pass the numeric team_id. Names like "Paris Saint-Germain" can collapse onto the wrong club (Paris FC) during name resolution.
• ClubElo off-season gaps: current-date get_team_strength can miss clubs in the summer break (a club's weekly Elo period may not span today). If a well-known club returns unresolved, pass an in-season date (e.g. date="2026-03-01").
• ClubElo outages: get_team_strength falls back to locally computed Elo and sets source: "local-elo". Check that field before comparing numbers across calls — the local scale is division-local, so a rating means nothing outside its own division and cross-division comparisons are refused. The fallback honours date (it rates the division as of that date, and each entry's as_of is the last match counted). get_match_forecast has no fallback and stays empty.
• `get_match_forecast` is short-horizon: ClubElo only forecasts ~a week ahead — empty between matchdays / off-season. That's expected, not a failure.
• H2H is same-division only: two clubs that met in a cup or across tiers won't show; it counts league meetings in the resolved division.
• H2H tells "unresolved" apart from "never met": football-data.co.uk uses short exonyms/abbreviations ("FC Koln", "M'gladbach", "Sp Lisbon"). Each club in teams[] reports resolved + matched_as; if a club is resolved: false, zero meetings means the lookup failed, not that the clubs never played.

Combining Endpoints (mix-and-match)

Compose sources for richer answers. Run independent calls in parallel.

• Match preview (X vs Y): search_team ×2 → get_head_to_head (recent record) + get_team_strength(team_id, team_id_2) (Elo gap / favorite) + get_match_forecast (if within ~a week: W/D/L + scoreline). For a top-5 fixture add historical get_event_xg context from recent meetings.
• Match report (post-game): get_event_summary + get_event_statistics + get_event_timeline, and for top-5 leagues get_event_xg + get_event_players_statistics.
• Team form + context: get_team_schedule (recent results) + get_team_strength (current Elo & rank) + get_missing_players (PL only) + per-match get_event_xg (top-5).
• Rivalry / derby deep dive: get_head_to_head (all-time-ish record + goals) + get_team_strength comparison for the current power balance.
• Odds sanity-check: get_match_forecast gives a free model baseline (W/D/L) to compare against the kalshi / polymarket betting skills.

When a piece of the composition isn't covered (e.g. xG outside the top 5, H2H for MLS), skip it silently and deliver the parts that are covered — don't block the whole answer on one missing source.

Commands