football-data

Football Data

设置

首次使用前，检查 CLI 是否可用：

which sports-skills || pip install sports-skills

如果 pip install 失败（找不到软件包或 Python 版本错误），请从 GitHub 安装：

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

此软件包要求 Python 3.10 或更高版本。如果默认 Python 版本较旧，请指定版本：

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

无需 API 密钥。

快速开始

优先使用 CLI，避免 Python 导入路径问题：

sports-skills football get_daily_schedule
sports-skills football get_season_standings --season_id=premier-league-2025

Python SDK（替代方式）：

from sports_skills import football

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

选择赛季

根据系统提示词中的日期推算当前年份（例如，currentDate: 2026-02-16 → 当前年份为 2026）。

• 如果用户指定了赛季，请按指定内容使用。
• 如果用户说“当前”“最新”或未指定赛季：调用 get_current_season(competition_id="...") 获取当前赛季的 season_id。不要猜测或硬编码年份。
• 赛季格式：始终使用 {league-slug}-{year}（例如，2025-26 赛季使用 "premier-league-2025"）。年份指赛季开始的年份，而不是结束年份。
• MLS 例外：MLS 在同一个日历年内进行春秋赛季。使用 get_current_season(competition_id="mls")，不要假设 MLS 遵循欧洲赛历。
• 切勿硬编码 season_id。 始终通过 get_current_season() 或系统日期推算。

各联赛的数据覆盖范围

并非所有联赛都提供全部数据。请为不同联赛使用正确的命令。

命令	全部 13 个联赛	仅前 5 个联赛	仅 PL
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

前 5 个联赛（Understat）：EPL、La Liga、Bundesliga、Serie A、Ligue 1。 仅 PL（FPL）：Premier League——伤病消息、球员数据、持有率、ICT 指数。 所有联赛：通过 ESPN 提供——比分、积分榜、赛程、比赛摘要、阵容、球队数据。 Transfermarkt：适用于任何具有 tm_player_id 的球员——市场估值和转会历史。

注意：MLS 使用不同的赛季结构（春秋赛历）。使用 get_current_season(competition_id="mls") 检测正确的 season_id。

ID 约定

• season_id：{league-slug}-{year}，例如 "premier-league-2025"、"la-liga-2025"
• competition_id：联赛 slug，例如 "premier-league"、"serie-a"、"champions-league"
• team_id：ESPN 球队 ID（数字字符串），例如 "359"（Arsenal）、"86"（Real Madrid）
• event_id：ESPN 比赛 ID（数字字符串），例如 "740847"
• fpl_id：FPL 元素 ID 或代码（仅限 PL 球员）
• tm_player_id：Transfermarkt 球员 ID，例如 "433177"（Saka）、"342229"（Mbappe）

命令

get_current_season

检测某项赛事的当前赛季。适用于所有联赛。

• competition_id（str，必填）：赛事 slug

返回 data.competition 和 data.season：

{"competition": {"id": "premier-league", "name": "Premier League"}, "season": {"id": "premier-league-2025", "name": "2025-26 English Premier League", "year": "2025"}}

get_competitions

列出可用赛事及其当前赛季信息。无需参数。适用于所有联赛。

返回包含 id、name、code、current_season 的 data.competitions[]。

get_competition_seasons

获取某项赛事的可用赛季。适用于所有联赛。

• competition_id（str，必填）：赛事 slug

get_season_schedule

获取完整赛季的比赛赛程。适用于所有联赛。

• season_id（str，必填）：赛季 slug（例如 "premier-league-2025"）

返回 data.schedules[]——结构与下文的 events 相同。

get_season_standings

获取某个赛季的联赛积分榜。适用于所有联赛。

• season_id（str，必填）：赛季 slug

返回 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

获取赛季得分手／领跑者。仅限 Premier League（通过 FPL）。

• season_id (str, required): 赛季标识（必须为 premier-league-*）

返回 data.leaders[] — 注意：球员姓名嵌套在 .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
}

对于非 PL 联赛，返回空结果。

get_season_teams

获取赛季中的球队。适用于所有联赛。

• season_id (str, required): 赛季标识

search_team

按名称搜索所有联赛中的球队（或指定联赛中的球队）。使用模糊匹配。

• query (str, required): 要搜索的球队名称（例如，“Corinthians”“Barcelona”“Man Utd”）
• competition_id (str, optional): 将搜索范围限制为一个联赛（例如，“serie-a-brazil”“premier-league”）

每个匹配结果都包含 team、competition 和 season，位于 data.results[] 中：

{"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_season_leaders 查找 PL 球员 ID，然后使用 get_player_profile 获取单个球员的数据。

• team_id (str, required): ESPN 球队 ID
• league_slug (str, optional): 联赛提示（可加快解析）

返回 data.team 和 data.venue。data.players[] 为空 — 推荐的工作流请参阅下方“深入了解 PL 球队”示例。

get_daily_schedule

获取指定日期所有联赛的比赛。

• date (str, optional): YYYY-MM-DD 格式的日期。默认为今天。

返回 data.date 和 data.events[]：

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

获取比赛摘要和比分。适用于所有联赛。

• event_id (str, required): 比赛／赛事 ID

返回 data.event（结构与每日赛程事件相同）。

get_event_lineups

获取比赛阵容。适用于所有联赛（以 ESPN 提供的数据为准）。

• event_id (str, required): 比赛／赛事 ID

返回 data.lineups[]：

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

获取比赛球队统计数据。适用于所有联赛。

• event_id (str, required): 比赛／赛事 ID

返回 data.teams[]：

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

获取比赛时间线／关键事件（进球、牌、换人）。适用于所有联赛。

• event_id (str, required): 比赛／赛事 ID

返回包含进球、牌和换人事件的 data.timeline[]。

get_team_schedule

获取指定球队的赛程 — 包括过去的赛果和即将进行的比赛。适用于所有联赛。

• team_id (str, required): ESPN 球队 ID
• league_slug (str, optional): 联赛提示（可加快解析）
• season_year (str, optional): 赛季年份筛选条件
• competition_id (str, optional): 将结果筛选为单个赛事（例如，“serie-a-brazil”“premier-league”）

get_head_to_head

不可用 — 需要获得授权的数据。请勿调用此命令；它会返回空结果。请改用 get_team_schedule 获取两支球队的赛程，并手动筛选重叠比赛。

• team_id (str, required): 第一支球队 ID
• team_id_2 (str, required): 第二支球队 ID

get_event_xg

获取来自 Understat 的预期进球（xG）数据。仅限五大联赛：EPL、La Liga、Bundesliga、Serie A、Ligue 1。其他联赛将返回空结果。

• event_id (str, required): 比赛／赛事 ID

返回 data.teams[] 和 data.shots[]：

{"team": {"id": "244", "name": "Brentford"}, "qualifier": "home", "xg": 1.812}

data.shots[] 包含每次射门的 xG 数据。注意：最近 24–48 小时内的比赛可能尚未被 Understat 收录。

get_event_players_statistics

获取球员级别的比赛统计数据，并补充 xG 数据。适用于所有联赛（基本统计数据来自 ESPN）。xG／xA 补充数据仅适用于五大联赛（Understat）。

• event_id (str, required): 比赛／赛事 ID

返回 data.teams[].players[]：

{
  "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 字段仅适用于五大联赛。

get_missing_players

获取受伤／缺阵／出战存疑的球员。仅限英超（通过 FPL 获取）。其他联赛返回空结果。

• season_id（str，必填）：赛季标识（必须为 premier-league-*）

返回 data.teams[].players[]：

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

状态值："injured"、"unavailable"、"doubtful"、"suspended"。

get_season_transfers

通过 Transfermarkt 获取特定球员的转会历史。适用于任何联赛。

• season_id（str，必填）：赛季标识（用于按年份筛选转会记录）
• tm_player_ids（list，必填）：Transfermarkt 球员 ID

返回 data.transfers[]：

{
  "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_season_stats

通过 ESPN 概览端点获取球员赛季数据。适用于任何拥有 ESPN 运动员 ID 的联赛。

• player_id（str，必填）：ESPN 运动员 ID
• league_slug（str，可选）：联赛标识提示（例如，"eng.1"、"esp.1"）。默认自动检测。

返回赛季数据（进球、助攻、出场次数等），以及可用时的比赛日志。

get_player_profile

获取球员资料。如果有球员的 Transfermarkt 或 FPL ID，则适用于任何球员。至少需要提供一个 ID。

• fpl_id（str，可选）：FPL 球员 ID（仅限英超球员）
• tm_player_id（str，可选）：Transfermarkt 球员 ID（适用于任何联赛）

提供 tm_player_id 时，返回包含以下内容的 data.player：

{
  "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 时，还会包含带有 FPL 数据的 data.player.fpl_data（积分、状态、ICT 指数、持有率等）。

支持的联赛

英超、西甲、德甲、意甲、法甲、MLS、英冠、荷甲、葡超、巴西甲、欧洲冠军联赛、欧洲杯、世界杯。

数据来源

来源	提供内容	覆盖联赛
ESPN	比分、积分榜、赛程、阵容、比赛数据、时间线	全部 13 个联赛
openfootball	赛程、积分榜、球队列表（ESPN 故障时的备用来源）	10 个联赛（除欧洲冠军联赛、欧洲杯、世界杯外）
Understat	每场比赛的 xG、每次射门的 xG、球员 xG/xA	前 5 大联赛（英超、西甲、德甲、意甲、法甲）
FPL	射手榜、伤病信息、球员数据、持有率	仅限英超
Transfermarkt	市场价值、转会历史	任何球员（需要 tm_player_id）

如需覆盖所有运动项目的授权数据（Sportradar、Opta、Genius Sports），请参阅 Machina Sports。

示例

用户：“给我看看英超积分榜”

1. 调用 get_current_season(competition_id="premier-league") 获取当前的 season_id
2. 调用 get_season_standings(season_id=<season_id from step 1>)
3. 展示积分榜，包含排名、球队、比赛场次、胜场、平局、负场、净胜球和积分

用户：“阿森纳对利物浦的比赛结果如何？”

1. 调用 get_daily_schedule() 或 get_team_schedule(team_id="359") 查找 event_id
2. 调用 get_event_summary(event_id="...") 获取比分
3. 调用 get_event_statistics(event_id="...") 获取控球率、射门数等数据
4. 调用 get_event_xg(event_id="...") 获取 xG 对比（仅限 EPL 前 5 名球队）
5. 展示比赛报告，包含比分、关键数据和 xG

用户：“深入分析切尔西近期的表现”

1. 调用 search_team(query="Chelsea") → team_id=363，competition=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=<season_id>) → 筛选切尔西受伤或出战存疑的球员
5. 调用 get_season_leaders(season_id=<season_id>) → 筛选切尔西球员并获取其 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. 如果是英超球员，可选地添加 fpl_id 以获取 FPL 数据
3. 展示市场价值、价值变动历史和转会历史

用户：“介绍一下科林蒂安”

1. 调用 search_team(query="Corinthians") → team_id=874，competition=serie-a-brazil
2. 调用 get_team_schedule(team_id="874", competition_id="serie-a-brazil") 获取赛程
3. 选择一场近期比赛并调用 get_event_timeline(event_id="...") 获取进球、牌和换人信息
4. 注意：巴西甲级联赛不提供 xG、FPL 数据和赛季领先者信息

错误处理

当命令失败时（例如 event_id 错误、缺少数据或网络错误），不要向用户显示原始错误。而应：

1. 静默捕获——将失败视为探索过程中的一次未命中，而非致命错误。
2. 尝试其他方法——例如，如果 event_id 没有返回数据，可调用 get_daily_schedule() 或 get_team_schedule() 来查找正确的 ID。如果 ESPN 无法访问，仍可通过 get_season_standings 或 get_season_schedule 获取 openfootball 数据。
3. 穷尽其他方法后再报告失败——此时应提供清晰易懂的消息（例如：“我找不到这场比赛——可以确认一下球队或日期吗？”），而不是显示回溯信息或原始 CLI 输出。

当 Agent 通过 Telegram、Slack 等消息平台回复时，这一点尤其重要，因为原始执行错误会让人觉得出了故障。

常见错误

以下是唯一有效的命令。 不要编造或猜测命令名称：

• get_current_season
• get_competitions
• get_competition_seasons
• get_season_schedule
• get_season_standings
• get_season_leaders
• get_season_teams
• search_team
• 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_profile
• get_player_season_stats

不存在的命令（常被凭空捏造）：

• get_standings — 正确的命令是 get_season_standings（需要 season_id）。
• get_live_scores — 不可用。使用 get_daily_schedule() 获取今日比赛；进行中的比赛会在状态字段中显示为 "live"。
• get_team_squad / get_team_roster — get_team_profile 不会返回球员。使用 get_season_leaders 获取 PL 球员 ID，然后使用 get_player_profile 获取个人数据。
• get_transfers — 正确的命令是 get_season_transfers（需要 season_id + tm_player_ids）。
• get_match_results / get_match — 使用 get_event_summary 并传入 event_id。
• get_player_stats — 比赛级统计数据使用 get_event_players_statistics，职业生涯数据使用 get_player_profile。

其他常见错误：

• 在非 PL 联赛中使用 get_season_leaders 或 get_missing_players — 结果为空。请查看 Data Coverage 表。
• 在前 5 大联赛以外的联赛中使用 get_event_xg — 结果为空。仅适用于 EPL、La Liga、Bundesliga、Serie A、Ligue 1。
• 不通过 search_team、get_daily_schedule 或 get_season_schedule 查询，直接猜测 team_id 或 event_id。

如果不确定某个命令是否存在，请查看此列表。不要尝试上面未列出的命令。

故障排除

• 找不到 sports-skills 命令：尚未安装软件包。运行 pip install sports-skills。如果在 PyPI 上找不到该软件包，请从 GitHub 安装：pip install git+https://github.com/machina-sports/sports-skills.git。需要 Python 3.10+ — 请参阅 Setup 部分。
• ModuleNotFoundError: No module named 'sports_skills'：同上 — 请安装该软件包。为避免路径问题，优先使用 CLI，而不是 Python 导入。
• 在其他联赛中使用仅适用于 PL 的命令，结果为空：get_season_leaders 和 get_missing_players 仅返回 Premier League 的数据。在其他联赛中，它们会直接返回空结果 — 请查看 Data Coverage 表。
• get_team_profile 返回的球员列表为空：这是预期行为 — 球队阵容名单不可用。要获取 PL 球队的球员数据，请使用 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") 查找 PL 球员的 FPL ID。Transfermarkt ID 必须在 transfermarkt.com 上查询 — 该 ID 是球员 URL 末尾的数字。知名球员示例：Cole Palmer = 568177，Bukayo Saka = 433177，Mbappe = 342229。
• 近期比赛没有 xG：比赛结束后，Understat 数据可能会延迟 24-48 小时。如果 get_event_xg 未返回近期前 5 大联赛比赛的数据，请稍后重试。
• season_id 格式错误：格式必须为 {league-slug}-{year}，例如 "premier-league-2025"。不能是 "2025-2026"，也不能是 "EPL-2025"。使用 get_current_season() 查询正确格式。
• 未知球队或赛事 ID：使用 search_team(query="team name") 按名称查找球队 ID，或使用 get_season_teams 列出某赛季的所有球队。使用 get_daily_schedule 或 get_season_schedule 查找赛事 ID。ID 是 ESPN 数字字符串。