football-data

足球数据

在编写查询前，请查阅 references/api-reference.md，了解端点、ID 约定和数据结构。

设置

首次使用前，检查 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()

重要：执行任何查询前

重要：调用任何数据端点前，请确认：

• 赛季 ID 通过 get_current_season(competition_id="...") 获取 — 绝不能硬编码。
• 球队 ID 通过 search_team(query="...") 解析，并以数值形式作为 team_id 传入。对于 get_head_to_head、get_team_strength 和 get_match_forecast，始终传入 ID — 名称可能有歧义（例如，两支球队都叫“Paris”），导致匹配到错误的球队。
• 端点确实覆盖所查询的联赛 — 请参阅下方的 覆盖范围与数据源对照表。各数据源的覆盖范围并不一致；未覆盖的调用会返回带有 message 的空载荷，而不是数据。
• get_event_xg 和 get_event_players_statistics（含 xG）仅用于五大联赛（EPL、La Liga、Bundesliga、Serie A、Ligue 1）。
• get_season_leaders 和 get_missing_players 仅用于 Premier League 赛季（season_id 必须以 premier-league- 开头）。

选择赛季

根据系统提示中的日期推算当前年份（例如，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")。

覆盖范围与数据源对照表

此技能整合了多个免费数据源。覆盖范围并不统一 — 每个端点仅适用于其底层数据源有数据的联赛。承诺回答前请先检查覆盖范围；如果端点未覆盖，该端点会返回带有说明性 message 的空载荷（不会报错）— 请阅读该消息并改用其他方式。

端点	数据源	覆盖范围
standings、schedules、teams、event summary/lineups/stats/timeline	ESPN	所有联赛（覆盖最广 — 核心数据源）
get_event_xg、get_event_players_statistics（xG 字段）	Understat	仅限五大联赛（EPL、La Liga、Bundesliga、Serie A、Ligue 1）。不包括 RFPL — Understat 已停止覆盖该联赛。Serie B 和 Championship 也不包括在内。
get_season_leaders、get_missing_players	FPL	仅限 Premier League
get_player_profile、get_season_transfers（市场价值）	Transfermarkt	任何具有 tm_player_id 的球员
get_head_to_head	football-data.co.uk	12 个欧洲国内联赛（EPL、Championship、La Liga、Serie A、Serie B、Bundesliga、Ligue 1、Eredivisie、Primeira Liga、Scottish、Belgian、Turkish）。仅包含同级联赛之间的交锋。
get_team_strength	ClubElo，失效时回退到本地 Elo	欧洲俱乐部（包括俄罗斯）。ClubElo 不可用时，回退到基于 football-data.co.uk 计算的评分。
get_match_forecast	ClubElo	欧洲俱乐部（包括俄罗斯）。无回退方案 — 需要 ClubElo 的赛程数据。

经验法则：ESPN 在所有地区回答“发生了什么”；补充数据源（Understat/FPL/ClubElo/football-data.co.uk）仅在其覆盖范围内提供更多信息。 ESPN 始终是赛程和比分的权威来源 — 绝不能让补充数据源覆盖 ESPN 的比分。

使用注意事项（实测所得）

• get_team_profile 会返回球队阵容。 data.players[] 包含当前名单，以及 ESPN 球员 ID、球衣号码和年龄——请使用它，而不是逐场收集球员姓名。
• get_player_season_stats 接受与其他所有接口相同的联赛 slug（serie-a-brazil，而不只是 ESPN 的 bra.1），其比赛日志涵盖最近约 5 场各项赛事，而不是整个赛季的数据。
• 罚进的点球在时间线中记为 penalty_goal。 与比分核对时，请统计 goal + penalty_goal + own_goal。
• 伤停补时字段为 added_time。 45+2′ 的事件为 minute: 45, added_time: 2（非伤停补时时为 0）。
• 传入球队 ID，不要用含糊的名称。 对于交锋记录、实力和预测，先用 search_team 解析球队，再传入数字 team_id。在名称解析过程中，像 “Paris Saint-Germain” 这样的名称可能会匹配到错误的俱乐部（Paris FC）。
• ClubElo 休赛期数据缺口：使用当前日期调用 get_team_strength 时，休赛期可能无法找到俱乐部（俱乐部的每周 Elo 周期可能不涵盖今天）。如果知名俱乐部返回未解析状态，请传入赛季中的日期（例如 date="2026-03-01"）。
• ClubElo 服务中断：get_team_strength 会回退到本地计算的 Elo，并设置 source: "local-elo"。跨调用比较数值前，请检查该字段——本地评分尺度按联赛分区划分，因此评分仅在所属分区内有意义，且不支持跨分区比较。回退逻辑会遵循 date（按该日期计算分区评分，每个条目的 as_of 为纳入计算的最后一场比赛日期）。get_match_forecast 没有回退机制，结果仍为空。
• get_match_forecast 的预测范围较短：ClubElo 只预测未来约一周的比赛——两轮比赛之间或休赛期可能返回空结果。这是预期行为，并非故障。
• 交锋记录仅限同一分区：两家俱乐部若曾在杯赛中交手或分属不同级别联赛，则不会显示；该接口统计的是已解析分区内的联赛交锋。
• 交锋记录会区分“未解析”和“从未交手”：football-data.co.uk 使用简短的外文名称或缩写（如 “FC Koln”、“M'gladbach”、“Sp Lisbon”）。teams[] 中每家俱乐部都会报告 resolved 和 matched_as；如果某家俱乐部的 resolved: false，那么交锋次数为 0 表示查询失败，而不是两队从未交手。

组合接口（灵活搭配）

组合多个数据源，提供更丰富的回答。相互独立的调用可以并行执行。

• 赛前预览（X vs Y）：调用两次 search_team → get_head_to_head（近期交锋记录）+ get_team_strength(team_id, team_id_2)（Elo 差距／热门球队）+ get_match_forecast（若比赛在约一周内：胜／平／负 + 比分预测）。对于排名前 5 的联赛赛事，可补充近期交锋的历史 get_event_xg 数据。
• 赛后报告：get_event_summary + get_event_statistics + get_event_timeline；对于排名前 5 的联赛，再加上 get_event_xg + get_event_players_statistics。
• 球队状态与背景：get_team_schedule（近期赛果）+ get_team_strength（当前 Elo 和排名）+ get_missing_players（仅限 PL）+ 按场调用 get_event_xg（排名前 5 的联赛）。
• 宿敌／德比深度分析：get_head_to_head（近似历史总交锋记录和进球数）+ get_team_strength 对比，以了解当前实力对比。
• 赔率合理性检查：get_match_forecast 提供免费的模型基准（胜／平／负），可与 kalshi / polymarket 下注技能的结果进行比较。

如果组合中某项内容不受支持（例如，排名前 5 的联赛之外的 xG、MLS 的交锋记录），请跳过该项，不作说明，提供其余可用内容即可——不要因为缺少一个数据源而阻碍整个回答。

命令

命令	描述
get_current_season	检测某项赛事的当前赛季
get_competitions	列出可用赛事及其当前赛季信息
get_competition_seasons	某项赛事的可用赛季
get_season_schedule	完整赛季的比赛日程
get_season_standings	某赛季的联赛积分榜
get_season_leaders	射手榜／领先者（仅限 Premier League）
get_season_teams	某赛季的球队
search_team	按名称搜索球队
search_player	按名称搜索球员
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_team_strength	Elo 评分／两队比较（欧洲俱乐部）；ClubElo 不可用时使用本地 Elo 备用方案
get_match_forecast	ClubElo 胜／平／负 + 比分预测（约提前一周）
get_event_xg	xG 数据（仅限五大联赛）
get_event_players_statistics	球员级比赛统计数据，可选包含 xG
get_missing_players	受伤／存疑球员（仅限 Premier League）
get_season_transfers	通过 Transfermarkt 查询转会历史
get_player_season_stats	通过 ESPN 查询球员赛季统计数据
get_player_profile	球员资料（FPL 和／或 Transfermarkt）

完整的参数列表、返回结构和数据覆盖表，请参阅 references/api-reference.md。

示例

示例 1：英超积分榜 用户说：“显示英超积分榜” 操作：

1. 调用 get_current_season(competition_id="premier-league") 获取当前的 season_id
2. 调用 get_season_standings(season_id=<season_id from step 1>) 结果：包含排名、球队、出场、胜、平、负、净胜球和积分的积分榜

示例 2：比赛报告 用户说：“阿森纳对阵利物浦的比赛结果如何？” 操作：

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 对比（英超——仅限前 5 名） 结果：包含比分、关键数据和 xG 的比赛报告

示例 3：深入分析球队 用户说：“深入分析切尔西近期的状态” 操作：

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、get_event_statistics、get_event_players_statistics
4. 调用 get_missing_players(season_id=<season_id>) → 筛选切尔西受伤或存疑的球员 结果：跨比赛的 xG 趋势、关键球员数据和伤病报告

示例 4：球员身价 用户说：“萨卡的身价是多少？” 操作：

1. 调用 get_player_profile(tm_player_id="433177") 获取 Transfermarkt 数据
2. 可选：添加 fpl_id 以获取 FPL 数据 结果：身价、身价历史和转会历史

示例 5：非英超俱乐部 用户说：“介绍一下科林蒂安” 操作：

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="...") 获取进球、红黄牌和换人信息 结果：赛程、比赛时间线事件（注意：巴西甲级联赛不提供 xG、FPL 数据和赛季领跑者数据）

示例 6：比赛前瞻（组合使用） 用户说：“前瞻一下本周末阿森纳对阵曼城的比赛” 操作：

1. 调用 search_team(query="Arsenal") 和 search_team(query="Manchester City") → team_ids 359、382
2. 并行调用：get_head_to_head(team_id="359", team_id_2="382")（近期交锋记录和进球数）， get_team_strength(team_id="359", team_id_2="382")（Elo 差距和热门球队）， get_match_forecast(team_id="359", team_id_2="382")（胜/平/负和可能比分，若比赛在约一周内举行）
3. 综合分析：状态/交锋记录 + 实力对比 + 模型赔率。忽略任何返回空结果的部分（例如，比赛在一周之后举行时的预测）。 结果：结合交锋历史、当前实力和免费模型预测的比赛前瞻

不存在的命令——切勿调用

• get_standings — 正确的命令是 get_season_standings（需要 season_id）。
• get_live_scores — 不可用。使用 get_daily_schedule() 查询当天的比赛。
• get_team_squad / get_team_roster — 使用 get_team_profile：data.players[] 是当前阵容，包含 ESPN 球员 ID（参见注意事项）。职业生涯数据仍需使用 get_season_leaders + get_player_profile。
• get_transfers — 正确的命令是 get_season_transfers（需要 season_id + tm_player_ids）。
• get_match_results / get_match — 使用带有 event_id 的 get_event_summary。
• get_player_stats — 比赛级数据使用 get_event_players_statistics，职业生涯数据使用 get_player_profile。
• get_scores / get_results — 使用带有 event_id 的 get_event_summary。
• get_fixtures — 使用 get_daily_schedule 查询当天的比赛，或使用 get_season_schedule 查询整个赛季的赛程。
• get_league_table — 使用带有 season_id 的 get_season_standings。

如果某个命令不在上方的 Commands 表格中，它就不存在。不要尝试未列出的命令。

错误处理

命令失败时（例如 event_id 错误、缺少数据、网络错误等），不要向用户显示原始错误。请改为：

1. 静默捕获错误——将失败视为一次探索性尝试未果。
2. 尝试其他方法——如果 event_id 没有返回数据，请调用 get_daily_schedule() 或 get_team_schedule() 查找正确的 ID。
3. 穷尽其他方法后再报告失败——使用简洁的消息（例如：“我找不到这场比赛——请确认球队或日期，可以吗？”）。

故障排除

错误：找不到 sports-skills 命令 原因：未安装软件包 解决方案：运行 pip install sports-skills。如果该软件包不在 PyPI 上，请从 GitHub 安装：pip install git+https://github.com/machina-sports/sports-skills.git

错误：ModuleNotFoundError: No module named 'sports_skills' 原因：未安装软件包或路径有问题 解决方案：安装软件包。建议使用 CLI，而非 Python 导入，以避免路径问题

错误：get_season_leaders 或 get_missing_players 在非 PL 联赛中返回空结果 原因：这些命令仅适用于英超；用于其他联赛时会静默返回空结果 解决方案：查看 references/api-reference.md 中的 Data Coverage 表。对于其他联赛，请使用 get_event_players_statistics 获取球员数据

错误：get_team_profile 未返回球员 原因：ESPN 中没有该球队 ID 对应联赛的阵容（league_slug 错误，或该球队是国家队／青年队） 解决方案：传入俱乐部所属联赛的 league_slug（例如 serie-a-brazil）；若要获取比赛日阵容，请使用 get_event_lineups

错误：season_id 格式错误 原因：Season ID 必须采用 {league-slug}-{year} 格式 解决方案：使用 get_current_season(competition_id="...") 查找正确格式。例如："premier-league-2025"，而不是 "2025-2026" 或 "EPL-2025"

错误：近期比赛没有 xG 数据 原因：比赛结束后，Understat 数据可能会延迟 24-48 小时 解决方案：如果 get_event_xg 对近期的五大联赛比赛返回空结果，请稍后重试。该数据仅适用于 EPL、La Liga、Bundesliga、Serie A、Ligue 1

错误：球队或赛事 ID 未知 原因：ID 是猜测的，而非查找得到的 解决方案：使用 search_team(query="team name") 查找球队 ID，或使用 get_daily_schedule / get_season_schedule 查找赛事 ID。切勿猜测 ID。