--- name: football-data description: | Football (soccer) data across 13 leagues — standings, schedules, match stats, xG, transfers, player profiles. Zero config, no API keys. Covers Premier League, La Liga, Bundesliga, Serie A, Ligue 1, MLS, Champions League, World Cup, Championship, Eredivisie, Primeira Liga, Serie A Brazil, European Championship.

Use when: user asks about football/soccer standings, fixtures, match stats, xG, lineups, player values, transfers, injury news, league tables, daily fixtures, or player profiles. Don't use when: user asks about American football/NFL (use nfl-data), college football (use cfb-data), NBA (use nba-data), WNBA (use wnba-data), college basketball (use cbb-data), NHL (use nhl-data), MLB (use mlb-data), tennis (use tennis-data), golf (use golf-data), Formula 1 (use fastf1), or betting odds (use polymarket or kalshi). Don't use for live/real-time scores — data updates post-match. Don't use get_season_leaders or get_missing_players for non-Premier League leagues (they return empty). Don't use get_event_xg for leagues outside the top 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1). license: MIT metadata: author: machina-sports version: "0.1.0" ---

Football Data

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()

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") — don't assume MLS follows European calendar.
• Never hardcode a season_id. Always derive it via get_current_season() or from the system date.

Data Coverage by League

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

| Command | All 13 leagues | Top 5 only | PL only | |---------|:-:|:-:|:-:| | get_season_standings | x | | | | get_daily_schedule | x | | | | get_season_schedule | x | | | | get_season_teams | x | | | | search_team | x | | | | get_team_schedule | x | | | | get_team_profile | x | | | | get_event_summary | x | | | | get_event_lineups | x | | | | get_event_statistics | x | | | | get_event_timeline | x | | | | get_current_season | x | | | | get_competitions | x | | | | get_event_xg | | x | | | get_event_players_statistics (with xG) | | x | | | get_season_leaders | | | x | | get_missing_players | | | x |

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.

ID Conventions

• season_id: {league-slug}-{year} e.g. "premier-league-2025", "la-liga-2025"
• 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)

Commands

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", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "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. Works for all leagues.

• competition_id (str, required): Competition slug

get_season_schedule

Get full season match schedule. Works for all leagues.

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

Returns data.schedules[] — same shape as events below.

get_season_standings

Get league table for a season. Works for all leagues.

• season_id (str, required): Season slug

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

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[] — 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_season_teams

Get teams in a season. Works for all leagues.

• season_id (str, required): Season slug

search_team

Search for a team by name across all leagues (or a specific one). Uses fuzzy matching.

• query (str, required): Team name to search (e.g., "Corinthians", "Barcelona", "Man Utd")
• competition_id (str, optional): Limit search to one league (e.g., "serie-a-brazil", "premier-league")

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"}}

get_team_profile

Get basic team info (name, crest, venue). Does not return squad/roster — use get_season_leaders to find PL player IDs, then get_player_profile for individual player data.

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

Returns data.team and data.venue. data.players[] is empty — see "Deep dive on a PL team" example below for the recommended workflow.

get_daily_schedule

Get all matches for a specific date across all leagues.

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

...