football-data
Football (soccer) data across the world's major leagues — standings, schedules, match stats, xG, transfers, player profiles, head-to-head history, team strength (Elo), and match forecasts. 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, Russian Premier League, Scottish/Belgian/Turkish top flights, European Championship, and more (call get_competitions for the live list). Use when: user asks about football/soccer standings, fixtures, match stats, xG, lineups, player values, transfers, injury news, league tables, daily fixtures, player profiles, head-to-head records, team strength/Elo ratings, or match odds/forecasts. 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)
machina-sports · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add machina-sports/sports-skills --skill football-data技能说明
name: football-data description: | Football (soccer) data across the world's major leagues — standings, schedules, match stats, xG, transfers, player profiles, head-to-head history, team strength (Elo), and match forecasts. 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, Russian Premier League, Scottish/Belgian/Turkish top flights, European Championship, and more (call get_competitions for the live list).
Use when: user asks about football/soccer standings, fixtures, match stats, xG, lineups, player values, transfers, injury news, league tables, daily fixtures, player profiles, head-to-head records, team strength/Elo ratings, or match odds/forecasts. 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), cricket (use cricket-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
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 numericteam_id. Forget_head_to_head,get_team_strength, andget_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_xgandget_event_players_statistics(with xG) are only called for top-5 leagues (EPL, La Liga, Bundesliga, Serie A, Ligue 1).get_season_leadersandget_missing_playersare only called for Premier League seasons (season_id must start withpremier-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.
| Endpoint(s) | Source | Coverage |
|---|---|---|
| standings, schedules, teams, event summary/lineups/stats/timeline | ESPN | All leagues (broadest — the backbone) |
get_event_xg, get_event_players_statistics (xG fields) | Understat | Top 5 only (EPL, La Liga, Bundesliga, Serie A, Ligue 1). Not RFPL — Understat dropped it. |
get_season_leaders, get_missing_players | FPL | Premier League only |
get_player_profile, get_season_transfers (market value) | Transfermarkt | Any player with a tm_player_id |
get_head_to_head | football-data.co.uk | 11 European domestic leagues (EPL, Championship, La Liga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, Scottish, Belgian, Turkish). Same-division meetings only. |
get_team_strength, get_match_forecast | ClubElo | European clubs (incl. Russia). |
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)
- Pass IDs, not ambiguous names. For H2H/strength/forecast, resolve teams with
search_teamfirst and pass the numericteam_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_strengthcan miss