SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场football-data

football-data

数据与分析

查看项目

更新于 10-15 12:39

技能介绍

用途

Football Data 用于以结构化方式获取足球（soccer）数据，面向需要查询联赛排名、赛程、比赛详情、预期进球（xG）、伤病名单和球员转会信息的场景。它作为技能（skill）集成，通过命令行或 Python 调用底层 sports-skills 包，零配置且无需 API 密钥。

安装与使用方式

首次使用前检查 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.12 -m pip install sports-skills，macOS 配合 Homebrew 时可用 /opt/homebrew/bin/python3.12 -m pip install sports-skills。

推荐使用 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 格式为 {league-slug}-{year}，年份为赛季的起始年（例如 2025-26 赛季写作 premier-league-2025）。当用户说“当前”“最新”或未指定时，应调用 get_current_season(competition_id="...") 获取活动赛季，不应猜测或硬编码年份。MLS 为春季至秋季的单一日历年赛季，需用 get_current_season(competition_id="mls") 判断。

主要能力与命令

  • get_current_season：检测某赛事的当前赛季，返回 competition 与 season 信息，适用于所有联赛。
  • get_competitions：列出可用赛事及其当前赛季，无参数。
  • get_competition_seasons：获取某赛事的可选赛季。
  • get_season_schedule：获取完整赛季赛程。
  • get_season_standings：获取赛季联赛积分榜，返回 position、team、played、won、drawn、lost、goals_for、goals_against、goal_difference、points。
  • get_season_leaders：获取赛季射手/领先者，仅英超（经 FPL）。
  • get_season_teams：获取赛季参赛球队。
  • search_team：按名称模糊搜索球队，可限定联赛。
  • get_team_profile：获取球队基本信息（名称、队徽、场地），不返回阵容。
  • get_daily_schedule：获取指定日期全部比赛，date 格式 YYYY-MM-DD，默认今天；状态值包括 not_started、live、halftime、closed、postponed。
  • get_event_summary：获取比赛摘要与比分。
  • get_event_lineups：获取比赛阵容，含阵型、首发与替补。
  • get_event_statistics：获取比赛球队统计，如控球、射门、射正、犯规、角球。
  • get_event_timeline：获取比赛时间线关键事件（进球、红黄牌、换人）。
  • get_team_schedule：获取某球队赛程，含过往结果与未来赛程。
  • get_event_xg：从 Understat 获取 xG 数据，仅前五大联赛，返回球队 xG 与逐脚射门 xG；最近 24-48 小时的比赛可能尚未收录。
  • get_event_players_statistics：获取球员级比赛统计，xG/xA 富化仅前五大联赛。
  • get_missing_players：获取受伤/缺阵/存疑球员，仅英超（经 FPL），状态值包括 injured、unavailable、doubtful、suspended。
  • get_season_transfers：经 Transfermarkt 获取指定球员转会历史。
  • get_player_season_stats：经 ESPN 概览端点获取球员赛季统计。
  • get_player_profile：获取球员资料，需提供 FPL ID 或 Transfermarkt ID（至少一个）；tm_player_id 返回市场价值、价值历史与转会历史，fpl_id 额外包含 FPL 数据。
  • get_head_to_head：不可用（需要授权数据），调用将返回空结果，应改用 get_team_schedule 手动筛选两队重叠比赛。

ID 约定

season_id 如 "premier-league-2025"；competition_id 如 "premier-league"、"serie-a"、"champions-league"；team_id 为 ESPN 球队数字 ID，如 "359"（阿森纳）；event_id 为 ESPN 赛事数字 ID，如 "740847"；fpl_id 为 FPL 球员 ID（仅英超）；tm_player_id 为 Transfermarkt 球员 ID，如 "433177"（萨卡）。

数据覆盖与来源

支持 13 个联赛：英超、西甲、德甲、意甲、法甲、MLS、英冠、荷甲、葡超、巴甲、欧冠、欧洲杯、世界杯。

数据源分工：ESPN 提供比分、积分榜、赛程、阵容、比赛统计与时间线，覆盖全部 13 个联赛；openfootball 提供赛程、积分榜与球队列表（ESPN 故障时的回退），覆盖 10 个联赛（除欧冠、欧洲杯、世界杯）；Understat 提供每场 xG、每脚射门 xG、球员 xG/xA，覆盖前五大联赛；FPL 提供射手榜、伤病、球员统计与持有率，仅英超；Transfermarkt 提供市场价值与转会历史，需要 tm_player_id。

适用场景示例

查询英超积分榜；查看阿森纳对利物浦的比赛结果、统计与 xG；深挖切尔西近期状态（结合球队赛程、逐场 xG/统计/球员数据、伤病名单与关键球员 FPL 及 Transfermarkt 数据）；查询萨卡的市场价值；了解科林蒂安（巴甲）的赛程与时间线。注意巴甲不支持 xG、FPL 统计和赛季领先者。

限制

get_head_to_head 因需授权数据不可用；xG 与球员 xG/xA 仅前五大联赛；赛季领先者、伤病名单仅英超；Transfermarkt 功能需提供球员 tm_player_id；部分联赛数据依赖 ESPN，若 ESPN 故障可回退 openfootball 的积分榜与赛程。

错误处理约定

命令失败（错误 event_id、数据缺失、网络错误等）时不应向用户暴露原始错误，应静默捕获并尝试替代方案（如用 get_daily_schedule 或 get_team_schedule 查找正确 ID，ESPN 故障时尝试 openfootball 数据），仅在穷尽替代方案后以人类可读的简洁信息报告失败，避免输出 traceback 或原始 CLI 内容。