Back to Details

football-data

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Football Data

足球数据工具

Setup

安装配置

Before first use, check if the CLI is available:
bash
which sports-skills || pip install sports-skills
If 
pip install
fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:
bash
python3 --version  # check version
首次使用前，检查CLI是否可用：
bash
which sports-skills || pip install sports-skills
如果
pip install
因Python版本错误失败，说明该包需要Python 3.10+版本。请找到兼容的Python版本：
bash
python3 --version  # 检查版本

If < 3.10, try: python3.12 -m pip install sports-skills

若版本 < 3.10，尝试：python3.12 -m pip install sports-skills

On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

在装有Homebrew的macOS上：/opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.
无需API密钥。

Quick Start

快速开始

Prefer the CLI — it avoids Python import path issues:
bash
sports-skills football get_daily_schedule
sports-skills football get_season_standings --season_id=premier-league-2025
Python SDK (alternative):
python
from sports_skills import football

standings = football.get_season_standings(season_id="premier-league-2025")
schedule = football.get_daily_schedule()
推荐使用CLI——可避免Python导入路径问题：
bash
sports-skills football get_daily_schedule
sports-skills football get_season_standings --season_id=premier-league-2025
Python SDK（替代方案）：
python
from sports_skills import football

standings = football.get_season_standings(season_id="premier-league-2025")
schedule = football.get_daily_schedule()

Data Coverage by League

各联赛数据覆盖情况

Not all data is available for every league. Use the right command for the right league.
CommandAll 13 leaguesTop 5 onlyPL only
get_season_standingsx
get_daily_schedulex
get_season_schedulex
get_season_teamsx
search_teamx
get_team_schedulex
get_team_profilex
get_event_summaryx
get_event_lineupsx
get_event_statisticsx
get_event_timelinex
get_current_seasonx
get_competitionsx
get_event_xgx
get_event_players_statistics (with xG)x
get_season_leadersx
get_missing_playersx
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.
并非所有数据在每个联赛都可用，请为对应联赛选择正确的命令。
命令全部13个联赛仅Top 5联赛仅Premier League
get_season_standingsx
get_daily_schedulex
get_season_schedulex
get_season_teamsx
search_teamx
get_team_schedulex
get_team_profilex
get_event_summaryx
get_event_lineupsx
get_event_statisticsx
get_event_timelinex
get_current_seasonx
get_competitionsx
get_event_xgx
get_event_players_statistics (带xG)x
get_season_leadersx
get_missing_playersx
Top 5联赛（数据来自Understat）：EPL、La Liga、Bundesliga、Serie A、Ligue 1。 仅Premier League（数据来自FPL）：伤病新闻、球员统计、球员持有率、ICT指数。 全部联赛：数据来自ESPN——比分、排名、赛程、赛事总结、首发阵容、球队统计。 Transfermarkt：适用于所有带有
tm_player_id
的球员——市场身价和转会历史。
注意：MLS采用不同的赛季结构（春秋赛制）。请使用
get_current_season(competition_id="mls")
检测正确的season_id。

ID Conventions

ID命名规则

  • 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)
  • season_id：
    {league-slug}-{year}
    例如 
    "premier-league-2025"
    , 
    "la-liga-2025"
  • competition_id：联赛缩写 例如 
    "premier-league"
    , 
    "serie-a"
    , 
    "champions-league"
  • team_id：ESPN球队ID（数字字符串）例如 
    "359"
    （阿森纳）, 
    "86"
    （皇家马德里）
  • event_id：ESPN赛事ID（数字字符串）例如 
    "740847"
  • fpl_id：FPL球员ID或编码（仅适用于Premier League球员）
  • tm_player_id：Transfermarkt球员ID 例如 
    "433177"
    （萨卡）, 
    "342229"
    （姆巴佩）

Commands

命令列表

get_current_season

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
:
json
{"competition": {"id": "premier-league", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "year": "2025"}}
检测指定赛事的当前赛季，支持所有联赛。
  • competition_id
    （字符串，必填）：赛事缩写
返回
data.competition
和
data.season
：
json
{"competition": {"id": "premier-league", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "year": "2025"}}

get_competitions

get_competitions

List available competitions with current season info. No params. Works for all leagues.
Returns 
data.competitions[]
with 
id
, 
name
, 
code
, 
current_season
.
列出所有可用赛事及当前赛季信息，无参数，支持所有联赛。
返回
data.competitions[]
，包含
id
、
name
、
code
、
current_season
字段。

get_competition_seasons

get_competition_seasons

Get available seasons for a competition. Works for all leagues.
  • competition_id
    (str, required): Competition slug
获取指定赛事的所有可用赛季，支持所有联赛。
  • competition_id
    （字符串，必填）：赛事缩写

get_season_schedule

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.
获取指定赛季的完整赛事赛程，支持所有联赛。
  • season_id
    （字符串，必填）：赛季缩写（例如"premier-league-2025"）
返回
data.schedules[]
——结构与下文的赛事数据一致。

get_season_standings

get_season_standings

Get league table for a season. Works for all leagues.
  • season_id
    (str, required): Season slug
Returns 
data.standings[].entries[]
:
json
{
  "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
}
获取指定赛季的联赛积分榜，支持所有联赛。
  • season_id
    （字符串，必填）：赛季缩写
返回
data.standings[].entries[]
：
json
{
  "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_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
:
json
{
  "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.
获取指定赛季的顶级射手/数据领跑者，仅支持Premier League（数据来自FPL）。
  • season_id
    （字符串，必填）：赛季缩写（必须为
    premier-league-*
    格式）
返回
data.leaders[]
——注意：球员名称嵌套在
.player.name
字段下：
json
{
  "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
}
针对非Premier League联赛调用会返回空值。

get_season_teams

get_season_teams

Get teams in a season. Works for all leagues.
  • season_id
    (str, required): Season slug
获取指定赛季的所有参赛球队，支持所有联赛。
  • season_id
    （字符串，必填）：赛季缩写

search_team

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:
json
{"team": {"id": "874", "name": "Corinthians"}, "competition": {"id": "serie-a-brazil", "name": "Serie A Brazil"}, "season": {"id": "serie-a-brazil-2025", "year": "2025"}}
按名称搜索球队（支持全联赛或指定联赛），使用模糊匹配。
  • query
    （字符串，必填）：球队名称（例如"Corinthians", "Barcelona", "Man Utd"）
  • competition_id
    （字符串，可选）：限制搜索范围到指定联赛（例如"serie-a-brazil", "premier-league"）
返回
data.results[]
，包含每个匹配结果的
team
、
competition
和
season
字段：
json
{"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_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.
获取球队基本信息（名称、队徽、主场）。不返回球队阵容——如需获取Premier League球队的球员数据，请先使用
get_season_leaders
获取球员FPL ID，再调用
get_player_profile
获取单个球员数据。
  • team_id
    （字符串，必填）：ESPN球队ID
  • league_slug
    （字符串，可选）：联赛提示（可加快查询速度）
返回
data.team
和
data.venue
字段。
data.players[]
为空——请参考下文“深度分析Premier League球队”示例中的推荐流程。

get_daily_schedule

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.
Returns 
data.date
and 
data.events[]
:
json
{
  "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"
.
获取指定日期全联赛的所有赛事。
  • date
    （字符串，可选）：日期格式为YYYY-MM-DD，默认值为今日。
返回
data.date
和
data.events[]
：
json
{
  "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}
}
状态值包括：
"not_started"
（未开赛）、
"live"
（进行中）、
"halftime"
（中场休息）、
"closed"
（已结束）、
"postponed"
（已延期）。

get_event_summary

get_event_summary

Get match summary with scores. Works for all leagues.
  • event_id
    (str, required): Match/event ID
Returns 
data.event
(same shape as daily schedule events).
获取赛事总结及比分，支持所有联赛。
  • event_id
    （字符串，必填）：赛事ID
返回
data.event
（结构与每日赛程中的赛事数据一致）。

get_event_lineups

get_event_lineups

Get match lineups. Works for all leagues (when available from ESPN).
  • event_id
    (str, required): Match/event ID
Returns 
data.lineups[]
:
json
{
  "team": {"id": "364", "name": "Liverpool", "abbreviation": "LIV"},
  "qualifier": "home",
  "formation": "4-3-3",
  "starting": [{"id": "275599", "name": "Caoimhín Kelleher", "position": "Goalkeeper", "shirt_number": 1}],
  "bench": [{"id": "...", "name": "...", "position": "...", "shirt_number": 62}]
}
获取赛事首发阵容，支持所有联赛（数据来自ESPN，需该赛事有相关数据）。
  • event_id
    （字符串，必填）：赛事ID
返回
data.lineups[]
：
json
{
  "team": {"id": "364", "name": "Liverpool", "abbreviation": "LIV"},
  "qualifier": "home",
  "formation": "4-3-3",
  "starting": [{"id": "275599", "name": "Caoimhín Kelleher", "position": "Goalkeeper", "shirt_number": 1}],
  "bench": [{"id": "...", "name": "...", "position": "...", "shirt_number": 62}]
}

get_event_statistics

get_event_statistics

Get match team statistics. Works for all leagues.
  • event_id
    (str, required): Match/event ID
Returns 
data.teams[]
:
json
{
  "team": {"id": "244", "name": "Brentford"},
  "qualifier": "home",
  "statistics": {"ball_possession": "40.8", "shots_total": "10", "shots_on_target": "3", "fouls": "12", "corners": "4"}
}
获取赛事球队统计数据，支持所有联赛。
  • event_id
    （字符串，必填）：赛事ID
返回
data.teams[]
：
json
{
  "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_timeline

get_event_timeline

Get match timeline/key events (goals, cards, substitutions). Works for all leagues.
  • event_id
    (str, required): Match/event ID
Returns 
data.timeline[]
with goal, card, and substitution events.
获取赛事时间线/关键事件（进球、出牌、换人），支持所有联赛。
  • event_id
    （字符串，必填）：赛事ID
返回
data.timeline[]
，包含进球、出牌和换人事件。

get_team_schedule

get_team_schedule

Get schedule for a specific team — includes both past results and upcoming fixtures. Works for all leagues.
  • team_id
    (str, required): ESPN team ID
  • league_slug
    (str, optional): League hint (faster resolution)
  • season_year
    (str, optional): Season year filter
  • competition_id
    (str, optional): Filter results to a single competition (e.g., "serie-a-brazil", "premier-league")
获取指定球队的赛程——包含过往战绩和未来赛事，支持所有联赛。
  • team_id
    （字符串，必填）：ESPN球队ID
  • league_slug
    （字符串，可选）：联赛提示（可加快查询速度）
  • season_year
    （字符串，可选）：赛季年份筛选
  • competition_id
    （字符串，可选）：筛选结果到指定赛事（例如"serie-a-brazil", "premier-league"）

get_head_to_head

get_head_to_head

UNAVAILABLE — requires licensed data. Do not call this command; it will return empty results. Instead, use 
get_team_schedule
for both teams and filter overlapping matches manually.
  • team_id
    (str, required): First team ID
  • team_id_2
    (str, required): Second team ID
不可用——需要授权数据。请勿调用该命令，会返回空结果。替代方案：分别调用两支球队的
get_team_schedule
，手动筛选重叠赛事。
  • team_id
    （字符串，必填）：第一支球队ID
  • team_id_2
    （字符串，必填）：第二支球队ID

get_event_xg

get_event_xg

Get expected goals (xG) data from Understat. Top 5 leagues only: EPL, La Liga, Bundesliga, Serie A, Ligue 1. Returns empty for other leagues.
  • event_id
    (str, required): Match/event ID
Returns 
data.teams[]
and 
data.shots[]
:
json
{"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.
获取赛事预期进球（xG）数据，数据来自Understat。仅支持Top 5联赛：EPL、La Liga、Bundesliga、Serie A、Ligue 1。针对其他联赛调用会返回空值。
  • event_id
    （字符串，必填）：赛事ID
返回
data.teams[]
和
data.shots[]
：
json
{"team": {"id": "244", "name": "Brentford"}, "qualifier": "home", "xg": 1.812}
data.shots[]
包含单脚射门的xG数据。注意：近期赛事（过去24-48小时）可能尚未在Understat完成索引。

get_event_players_statistics

get_event_players_statistics

Get player-level match statistics with xG enrichment. Works for all leagues (basic stats from ESPN). xG/xA enrichment only for top 5 leagues (Understat).
  • event_id
    (str, required): Match/event ID
Returns 
data.teams[].players[]
:
json
{
  "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.
获取球员级别的赛事统计数据，并附带xG增强信息。支持所有联赛（基础数据来自ESPN）。仅Top 5联赛会附带xG/xA增强数据（来自Understat）。
  • event_id
    （字符串，必填）：赛事ID
返回
data.teams[].players[]
：
json
{
  "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
和
xa
字段仅在Top 5联赛的结果中存在。

get_missing_players

get_missing_players

Get injured/missing/doubtful players. Premier League only (via FPL). Returns empty for other leagues.
  • season_id
    (str, required): Season slug (must be 
    premier-league-*
    )
Returns 
data.teams[].players[]
:
json
{
  "id": "463748", "name": "Mikel Merino Zazón", "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"
.
获取受伤/缺席/存疑的球员数据，仅支持Premier League（数据来自FPL）。针对其他联赛调用会返回空值。
  • season_id
    （字符串，必填）：赛季缩写（必须为
    premier-league-*
    格式）
返回
data.teams[].players[]
：
json
{
  "id": "463748", "name": "Mikel Merino Zazón", "web_name": "Merino",
  "position": "Midfielder", "status": "injured",
  "news": "脚部受伤——归期未定",
  "chance_of_playing_this_round": 0, "chance_of_playing_next_round": 0
}
状态值包括：
"injured"
（受伤）、
"unavailable"
（缺席）、
"doubtful"
（存疑）、
"suspended"
（停赛）。

get_season_transfers

get_season_transfers

Get transfer history for specific players via Transfermarkt. Works for any league.
  • season_id
    (str, required): Season slug (used to filter transfers by year)
  • tm_player_ids
    (list, required): Transfermarkt player IDs
Returns 
data.transfers[]
:
json
{
  "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": "-"
}
获取指定赛季的球员转会历史，数据来自Transfermarkt。支持所有联赛。
  • season_id
    （字符串，必填）：赛季缩写（用于按年份筛选转会）
  • tm_player_ids
    （列表，必填）：Transfermarkt球员ID列表
返回
data.transfers[]
：
json
{
  "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

get_player_profile

Get player profile. Works for any player if you have their Transfermarkt or FPL ID. At least one ID required.
  • fpl_id
    (str, optional): FPL player ID (PL players only)
  • tm_player_id
    (str, optional): Transfermarkt player ID (any league)
With 
tm_player_id
, returns 
data.player
with:
json
{
  "market_value": {"value": 130000000, "currency": "EUR", "formatted": "€130.00m", "date": "09/12/2025", "age": "24", "club": "Arsenal FC"},
  "market_value_history": [{"value": 7000000, "formatted": "€7.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.).
获取球员资料，只要拥有该球员的Transfermarkt或FPL ID，即可支持所有联赛。至少需要提供一个ID。
  • fpl_id
    （字符串，可选）：FPL球员ID（仅适用于Premier League球员）
  • tm_player_id
    （字符串，可选）：Transfermarkt球员ID（适用于所有联赛）
提供
tm_player_id
时，返回
data.player
包含以下内容：
json
{
  "market_value": {"value": 130000000, "currency": "EUR", "formatted": "€130.00m", "date": "09/12/2025", "age": "24", "club": "Arsenal FC"},
  "market_value_history": [{"value": 7000000, "formatted": "€7.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": "-"}
  ]
}
提供
fpl_id
时，还会包含
data.player.fpl_data
字段，包含FPL统计数据（积分、状态、ICT指数、持有率等）。

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.
Premier League、La Liga、Bundesliga、Serie A、Ligue 1、MLS、Championship、Eredivisie、Primeira Liga、Serie A Brazil、Champions League、European Championship、World Cup。

Data Sources

数据来源

SourceWhat it providesLeague coverage
ESPNScores, standings, schedules, lineups, match stats, timelinesAll 13 leagues
openfootballSchedules, standings, team lists (fallback when ESPN is down)10 leagues (all except CL, Euros, World Cup)
UnderstatxG per match, xG per shot, player xG/xATop 5 (EPL, La Liga, Bundesliga, Serie A, Ligue 1)
FPLTop scorers, injuries, player stats, ownershipPremier League only
TransfermarktMarket values, transfer historyAny player (requires tm_player_id)
For licensed data with full coverage across all sports (Sportradar, Opta, Genius Sports), see Machina Sports.
来源提供内容联赛覆盖范围
ESPN比分、排名、赛程、首发阵容、赛事统计、时间线全部13个联赛
openfootball赛程、排名、球队列表（ESPN故障时的备选来源）10个联赛（不含Champions League、European Championship、World Cup）
Understat赛事xG、单脚射门xG、球员xG/xATop 5联赛（EPL、La Liga、Bundesliga、Serie A、Ligue 1）
FPL顶级射手、伤病、球员统计、持有率仅Premier League
Transfermarkt市场身价、转会历史所有联赛（需球员有tm_player_id）
如需覆盖所有体育项目的授权数据（Sportradar、Opta、Genius Sports），请访问Machina Sports。

Examples

使用示例

User: "Show me the Premier League table"
  1. Call 
    get_current_season(competition_id="premier-league")
    to get current season_id
  2. Call 
    get_season_standings(season_id="premier-league-2025")
  3. Present standings table with position, team, played, won, drawn, lost, GD, points
User: "How did Arsenal vs Liverpool go?"
  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)
  5. Present match report with scores, key stats, and xG
User: "Deep dive on Chelsea's recent form"
  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(event_id="...")
      for xG comparison and shot map
    • get_event_statistics(event_id="...")
      for possession, shots, passes
    • get_event_players_statistics(event_id="...")
      for individual player xG/xA
  4. Call 
    get_missing_players(season_id="premier-league-2025")
    → filter Chelsea's injured/doubtful players
  5. Call 
    get_season_leaders(season_id="premier-league-2025")
    → filter Chelsea players, get their FPL IDs
  6. Call 
    get_player_profile(fpl_id="...", tm_player_id="...")
    for key players — combine FPL stats (form, ownership, ICT) with Transfermarkt data (market value, transfer history)
  7. Present: xG trend across matches, key player stats, injury report, market values
User: "What's Saka's market value?"
  1. Call 
    get_player_profile(tm_player_id="433177")
    for Transfermarkt data
  2. Optionally add 
    fpl_id
    for FPL stats if Premier League player
  3. Present market value, value history, and transfer history
User: "Tell me about Corinthians"
  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
  4. Note: xG, FPL stats, and season leaders are NOT available for Brazilian Serie A
用户：“展示Premier League积分榜”
  1. 调用
    get_current_season(competition_id="premier-league")
    获取当前赛季的season_id
  2. 调用
    get_season_standings(season_id="premier-league-2025")
  3. 展示包含排名、球队、场次、胜场、平场、负场、净胜球、积分的积分榜
用户：“阿森纳vs利物浦的比赛结果如何？”
  1. 调用
    get_daily_schedule()
    或
    get_team_schedule(team_id="359")
    找到赛事ID
  2. 调用
    get_event_summary(event_id="...")
    获取比分
  3. 调用
    get_event_statistics(event_id="...")
    获取控球率、射门数等数据
  4. 调用
    get_event_xg(event_id="...")
    获取xG对比数据（仅适用于EPL这类Top 5联赛）
  5. 展示包含比分、关键统计数据和xG的赛事报告
用户：“深度分析切尔西近期状态”
  1. 调用
    search_team(query="Chelsea")
    → team_id=363，赛事为premier-league
  2. 调用
    get_team_schedule(team_id="363", competition_id="premier-league")
    → 找到近期已结束的赛事
  3. 并行调用以下接口获取每场近期赛事的数据： 
    • get_event_xg(event_id="...")
      获取xG对比和射门分布图
    • get_event_statistics(event_id="...")
      获取控球率、射门数、传球数
    • get_event_players_statistics(event_id="...")
      获取单个球员的xG/xA数据
  4. 调用
    get_missing_players(season_id="premier-league-2025")
    → 筛选切尔西的受伤/存疑球员
  5. 调用
    get_season_leaders(season_id="premier-league-2025")
    → 筛选切尔西球员，获取他们的FPL ID
  6. 调用
    get_player_profile(fpl_id="...", tm_player_id="...")
    获取关键球员数据——结合FPL统计数据（状态、持有率、ICT指数）和Transfermarkt数据（市场身价、转会历史）
  7. 展示：赛事xG趋势、关键球员统计、伤病报告、市场身价
用户：“萨卡的市场身价是多少？”
  1. 调用
    get_player_profile(tm_player_id="433177")
    获取Transfermarkt数据
  2. 若该球员是Premier League球员，可额外添加
    fpl_id
    获取FPL统计数据
  3. 展示市场身价、身价历史和转会历史
用户：“介绍一下Corinthians”
  1. 调用
    search_team(query="Corinthians")
    → team_id=874，赛事为serie-a-brazil
  2. 调用
    get_team_schedule(team_id="874", competition_id="serie-a-brazil")
    获取赛程
  3. 选择一场近期赛事，调用
    get_event_timeline(event_id="...")
    获取进球、出牌、换人事件
  4. 注意：巴西Serie A联赛不支持xG、FPL统计和赛季领跑者数据

Troubleshooting

故障排除

  • sports-skills
    command not found    : Package not installed. Run 
    pip install sports-skills
    . If pip fails with a Python version error, you need Python 3.10+ — see Setup section.
  • ModuleNotFoundError: No module named 'sports_skills'
    : Same as above — install the package. Prefer the CLI over Python imports to avoid path issues.
  • Empty results for PL-only commands on other leagues: 
    get_season_leaders
    and 
    get_missing_players
    only return data for Premier League. They silently return empty for other leagues — check the Data Coverage table.
  • get_team_profile
    returns empty players    : This is expected — squad rosters are not available. To get player data for a PL team, use 
    get_season_leaders
    to find players and their FPL IDs, then 
    get_player_profile(fpl_id="...")
    for detailed stats. For Transfermarkt data, you need the player's 
    tm_player_id
    .
  • Finding FPL IDs and Transfermarkt IDs: Use 
    get_season_leaders(season_id="premier-league-2025")
    to discover FPL IDs for PL players. Transfermarkt IDs must be looked up on transfermarkt.com — the ID is the number at the end of the player's URL. Well-known examples: Cole Palmer = 
    568177
    , Bukayo Saka = 
    433177
    , Mbappe = 
    342229
    .
  • No xG for recent matches: Understat data may lag 24-48 hours after a match ends. If 
    get_event_xg
    returns empty for a recent top-5 match, try again later.
  • Wrong season_id format: Must be 
    {league-slug}-{year}
    e.g. 
    "premier-league-2025"
    . Not 
    "2025-2026"
    , not 
    "EPL-2025"
    . Use 
    get_current_season()
    to discover the correct format.
  • Team/event IDs unknown: Use 
    search_team(query="team name")
    to find team IDs by name, or 
    get_season_teams
    to list all teams in a season. Use 
    get_daily_schedule
    or 
    get_season_schedule
    to find event IDs. IDs are ESPN numeric strings.
  • sports-skills
    命令未找到    ：未安装该包。请运行
    pip install sports-skills
    。若pip因Python版本错误失败，说明你需要Python 3.10+版本——请参考安装配置部分。
  • ModuleNotFoundError: No module named 'sports_skills'
    ：原因同上——请安装该包。推荐使用CLI而非Python导入，以避免路径问题。
  • 针对非Premier League联赛调用仅PL可用的接口返回空值：
    get_season_leaders
    和
    get_missing_players
    仅返回Premier League的数据。针对其他联赛调用会静默返回空值——请参考数据覆盖情况表格。
  • get_team_profile
    返回空的players字段    ：这是预期行为——不提供球队阵容数据。如需获取Premier League球队的球员数据，请使用
    get_season_leaders
    找到球员及其FPL ID，再调用
    get_player_profile(fpl_id="...")
    获取详细统计。如需Transfermarkt数据，你需要球员的
    tm_player_id
    。
  • 如何查找FPL ID和Transfermarkt ID：使用
    get_season_leaders(season_id="premier-league-2025")
    获取Premier League球员的FPL ID。Transfermarkt ID需要在transfermarkt.com上查找——ID是球员URL末尾的数字。知名球员示例：Cole Palmer = 
    568177
    ，Bukayo Saka = 
    433177
    ，Mbappe = 
    342229
    。
  • 近期赛事无xG数据：Understat的数据可能在赛事结束后24-48小时内完成索引。若针对近期Top 5联赛赛事调用
    get_event_xg
    返回空值，请稍后重试。
  • season_id格式错误：必须为
    {league-slug}-{year}
    格式，例如
    "premier-league-2025"
    。不支持
    "2025-2026"
    或
    "EPL-2025"
    格式。请使用
    get_current_season()
    获取正确格式。
  • 未知球队/赛事ID：使用
    search_team(query="球队名称")
    按名称查找球队ID，或使用
    get_season_teams
    列出指定赛季的所有球队。使用
    get_daily_schedule
    或
    get_season_schedule
    查找赛事ID。ID为ESPN的数字字符串。