足球数据

要解决什么问题

分析足球数据时，摩擦通常不在分析本身，而在数据接入：申请 API key、配置 SDK 环境、处理球队 ID 与赛季 ID 的映射关系。尤其当查询涉及同名俱乐部（比如两座“巴黎”）或跨赛季对比时，按名称查库很容易命中错误对象，后续统计结论也会跟着失真。这个技能把数据获取环节收敛为一套带校验的调用流程，免去密钥配置，直接返回结构化的比赛、球队与球员数据。

技能如何工作

核心能力围绕三类查询：赛季与球队元数据、对阵记录（历史交锋、球队实力对比、比赛预测），以及赛事级事件统计。关键步骤在调用任何数据端点之前，技能会强制完成三件事：

• 通过 get_current_season(competition_id) 动态推导赛季 ID，赛季标识不写死；
• 通过 search_team(query) 将队名解析为数字 team_id，再传给后续接口；
• 调用前核对该端点是否覆盖目标联赛，相关约定记录在 references/api-reference.md。

CLI 是推荐入口，它绕开了 Python 导入路径问题；Python SDK 作为备选方案存在。首次运行前应确认 CLI 可用，环境需要 Python 3.10 及以上，全程不需要 API key。

适用边界与注意点

覆盖范围并不均匀。每个端点都有对应的 Coverage & Source Map，如果查询的联赛不在覆盖列表内，接口不会报错，而是返回空 payload 并附带说明消息，调用方需要自行区分“无数据”与“请求失败”。

高级统计有明确的联赛门槛：

• 事件级 xG 与含 xG 的球员详细统计仅覆盖五大联赛：英超、西甲、德甲、意甲、法甲；
• 赛季射手榜与缺阵名单接口只支持英超赛季，且 season_id 必须以 premier-le 开头。

此外，凡涉及具体球队的接口——历史交锋、球队实力、比赛预测——都必须传 ID 而非队名。同名俱乐部是真实存在的风险，按名称解析可能落到另一支球队上，统计口径随之错位。