4.7 核心接口精讲③:球队与球员高阶档案
精讲把下面这段发给你的 AI,它就知道该做什么
点「复制全文」,粘贴到你的 AI 对话框发送即可,无需改动。
你正在阅读球小策(www.qiuxiaoce.com)的官方文档或数据服务页面。请按下面 5 步执行,不要跳步。
【预备】我的专属数据密钥是 X-API-Key = [在此粘贴你的 Key]
(第 2 步和第 3 步都会用到它;还没有密钥,先到 https://www.qiuxiaoce.com/data-account/ 免费领取)
━━━ 第 0 步 · 三条硬性纪律 ━━━
1. 凡涉及指标定义、接口参数、计费规则、准确率口径的问题,一律以站内官方文档为准,不要凭记忆作答;文档里没写的,就直接告诉我「文档未说明」。
2. 如果你无法访问下面任何一个网址,请立刻停下来告诉我,不要用记忆里的内容顶替。
3. 本站只做数据分析,不提供任何投注建议,也不做准确率承诺。回答时请守住这条边界。
━━━ 第 1 步 · 遍历官方文档(100+ 篇,按需取,别一次全拉)━━━
· 取全量目录(公开接口,无需密钥,返回全部篇章的标题与 slug):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs
· 读单篇正文(把 {slug} 换成上一步拿到的标识):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs/{slug}
· 人读版页面(适合只能浏览网页、拿不到 JSON 的环境):
https://www.qiuxiaoce.com/creator-docs/{slug}/
· 接口文档(全部数据接口的用途、参数、计费与真实返回示例):
https://www.qiuxiaoce.com/data-docs/
做法:先取目录 → 判断我的问题涉及哪几篇 → 只读那几篇 → 回答时注明依据的篇名或链接。
━━━ 第 2 步 · 先判断你自己的能力,再选路径(关键,不可跳过)━━━
· A 类:能在本机读写文件或执行命令——桌面/终端类 AI 工具(WorkBuddy、Qoder、Trae 等)
· B 类:只能对话,访问不了文件系统——网页版对话(豆包、通义千问、Kimi 等)
【A 类 · 安装官方 Skill(推荐)】
1. 取最新版本信息:
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/skill/version
返回 version、download_url、sha256 校验清单、文件列表与更新说明。
2. 按 download_url 下载技能包,并用返回的 sha256 逐文件校验。
3. 解压到你的技能目录,保持包内顶层目录结构;按包内 SKILL.md 完成初始化。
4. 写入我的专属密钥(即上文【预备】里的 X-API-Key)。
5. 装完告诉我:版本号、安装位置、密钥是否已生效。
【B 类 · 装不了就照实说,不要假装】
不要声称已安装,也不要拿记忆里的内容替代文档。请直接对我说:
「当前环境不支持安装 Skill(无法读写本地文件)。有两个办法:
① 改用支持 Skill 的桌面 AI 工具,如 WorkBuddy、Qoder、Trae;
② 把你的 API Key 给我,我按官方接口文档直接取数分析。」
如果你连「打开指定网址」都做不到,请把这一点也一并告诉我。
━━━ 第 3 步 · 直接用接口取数(两条路径都适用)━━━
· 接口根地址:https://www.qiuxiaoce.com/wp-json/abv2-creator/v1
· 认证方式:请求头带上【预备】里的 X-API-Key
· 想先试不扣点数的接口,看 https://www.qiuxiaoce.com/data-docs/ 里标注为免费的端点。
· 大批量调用前先查一次剩余点数,避免跑到一半失败。
━━━ 第 4 步 · 遇到报错,先查官方排障手册再重试 ━━━
排障手册:https://www.qiuxiaoce.com/creator-docs/api-error-codes-troubleshooting/
· 401:Key 缺失、格式不对,或该 Key 已被重置/吊销(控制台执行「重置 Key」后旧 Key 立即失效,错误码 api_key_revoked 即属此类)→ 到 https://www.qiuxiaoce.com/data-account/ 复制最新完整 Key,并同步更新所有已配置该 Key 的脚本与客户端
· 402:点数不足或已过期 → 需到 https://www.qiuxiaoce.com/data-service/ 充值
· 403:接口未开放,或权限不足(个别场次报告需要订阅)
· 404:实体 ID 或接口路径写错
· 429:请求过快,按响应头 Retry-After 等待后重试
报错时请把原始错误信息原样转述给我,不要猜原因。
━━━ 第 5 步 · 回答我时的要求 ━━━
· 区分「官方事实数据」「接口返回的判断字段」「衍生评分」「你自己的推断」四类,不要混着说。
· 使用 xG、xGA、OTI、DII 这类指标前,先按文档校正口径;样本不足要在结论里注明。
· 缺数据就说缺什么,不要用「大概」「可能」糊过去。
· 不给投注建议,不承诺准确率。
· 如果回答主要依据了某篇文档,请把链接带上,方便我自己核对。
这一篇讲球队域、球员域,以及容易被忽略的教练与裁判。核心是三个「值钱」的接口:球队高阶画像、伤停名单、球员高阶指标。
一、球队域有哪些接口,分别值不值?
| 接口 | 给你什么 | 点数 | 性价比 |
|---|---|---|---|
/teams?q= |
球队搜索,拿 team_id | 2 | 必需(前置步骤) |
/teams/{id} |
球队详情(三字码、国家、球场、容量) | 2 | 补充背景时用 |
/teams/{id}/form |
近期战绩(近 N 场逐场) | 5 | 高 |
/teams/{id}/statistics |
赛季统计(进失球、零封、最长连胜等) | 5 | 高 |
/teams/{id}/advanced |
高阶画像 | 10 | 很高 |
/teams/{id}/injuries |
伤停名单 | 5 | 很高 |
/teams/{id}/players-advanced |
队内球员高阶 TOP(最多 20 人) | 10 | 很高 |
二、/teams/{id}/advanced 高阶画像里有什么?
这是球队域的主力接口,一次给你:
- 预期数据:预期进球、预期失球、差值;
- 进攻:场均进球、场均射正、绝佳机会与错失、对方禁区触球、角球、定位球进球、判罚点球数;
- 防守:失球、零封等防守侧统计;
- 控球:场均控球率、场均传球成功率等;
- 纪律:场均犯规、黄牌、红牌;
- 其他:常用阵型、近期走势、场均评分、阵容身价、联赛排名。
为什么它比
/statistics贵一倍(10 点 vs 5 点)?因为它多了预期数据与更细的攻防拆解——而那才是判断「实力」而不是「战绩」的关键。如果你只是想看积分和进失球,用 5 点的接口就够了。
三、伤停名单为什么是性价比之王?
/teams/{id}/injuries 只要 5 点,给的是当前伤停:球员名、伤情类型、预计回归时间、是否存疑。
它便宜,但它往往是整篇分析里信息增量最大的一项——因为赛前的所有模型都是在「过往数据」上算的,只有伤停是「未来的变化」。一支球队的高阶数据再好,核心缺阵就是另一回事。
两个使用要点:
- 注意时效。伤停数据缓存约 6 小时,越临近开赛变化越剧烈,引用前最好重取一次;
- 别把存疑当确定。标注存疑的球员可能首发也可能不首发,正确做法是分两种情形讨论,而不是取中间值。
四、球员域最常见的花钱错误是什么?
| 接口 | 用途 | 点数 |
|---|---|---|
/players?q= |
球员搜索 | 2 |
/players/{id} |
球员详情(含现属球队、身价) | 2 |
/players/{id}/stats |
赛季统计 | 3 |
/players/{id}/advanced |
单人高阶指标 | 3 |
/teams/{id}/players-advanced |
整队球员高阶(最多 20 人) | 10 |
要取一支球队多名球员的高阶数据,必须用
/teams/{id}/players-advanced。逐个调单人接口的话,查 10 个人要 30 点,而批量接口一次只要 10 点——这是最常见的点数浪费。单人接口只在「我只要查这一个人」时使用。
队内球员高阶返回的字段包括:进攻威胁、防守参与度、比赛影响力、即时战力与走势、稳定性、疲劳负荷,以及球员级的预期进球与预期助攻。完整字段说明见 3.5 GIM 比赛影响力 与 3.6 阵容完整度。
同一份数据还带 xg_metrics:球员级预期进球(xg)、预期助攻(xa)及各自的每 90 分钟值。口径与使用注意见 3.2 xG 与 xGA。注意:没有数据的球员不会出现这个字段,所以写代码时要先判断键是否存在,不要假设一定有值。
用这些字段时有哪三条口径红线?
- 防守参与度(DII)不代表防守强弱——它统计的是防守动作数量,与失球、预期失球都不相关。判断防守质量要看预期失球与零封率;
- 「样本量不足」标记不等于数据是编造的——它只表示该球员本赛季累计出场时间偏少,数值仍由真实逐场数据算出;
- 缺失值就是缺失——接口没返回的字段是「当前没有」,不要写成 0%,也不要估算。
五、完整的球队评估流程要花多少点?
/teams?q=队名→ 拿 team_id(2 点);/teams/{id}/advanced→ 高阶画像(10 点);/teams/{id}/injuries→ 伤停(5 点);/teams/{id}/players-advanced→ 核心球员(10 点);- 把三份数据交给 AI → 输出球队评估。
合计 27 点(约 0.27 元),就能建立一支球队的完整档案。如果要对比两支球队,翻倍即可。
六、教练与裁判也别忽略
/teams/{id}/coach(3 点)拿现任教练的 ID,再用/coaches/{id}(3 点)看完整执教履历与惯用阵型——用于判断战术取向与临场调整风格;/fixtures/{id}里的referee字段拿到裁判姓名,再用/referees?q=姓名(2 点)解析 ID,最后/referees/{id}(3 点)看执法数据(场均出牌数等)。
这两个维度常被忽略,但写「比赛会怎么踢」时它们常常是最有个性的素材。注意裁判数据来自姓名匹配,同名裁判理论上有歧义,引用时留个心。
下一步该看什么
- 报错与限流怎么处理 → 4.8 错误码与排障
- 阵容与伤停怎么折算影响 → 3.6 阵容完整度
- 把这些接口交给 AI 自动执行 → 5.1 一键挂载 Skill
足球赛事前瞻 | AI 智能分析 | 足球数据解读 - 球小策