接口文档
足球赛事数据结构化接口的字段说明与调用方式,面向已获得授权卡密的用户。
基础地址 https://huhuan.hb.cn
0. 响应压缩(必读)
2026-11-11 起,所有接口的响应均经 gzip 压缩。客户端若未解压,会拿到二进制乱码, 典型表现为「数据为空」「JSON 解析失败」「UnicodeDecodeError」——这不是接口故障。
关键:是否压缩与请求头无关。即使你发送 Accept-Encoding: identity,或完全不发送该头,
服务端仍返回 Content-Encoding: gzip 的压缩内容。
响应长度小于 1024 字节时(例如空结果)不压缩,此时没有该响应头。
请一律按响应头的 Content-Encoding 判断,不要写死。
| 语言 / 库 | 是否自动解压 | 需要的动作 |
|---|---|---|
| curl | 否 | 加 --compressed |
Python requests / httpx | 是 | 无需改动 |
Python urllib / http.client | 否 | 手动 gzip.decompress,见下 |
Node.js axios / 原生 fetch | 是 | 无需改动 |
Java OkHttp / .NET HttpClient | 是 | 无需改动 |
PHP curl | 否 | 设 CURLOPT_ENCODING |
PHP file_get_contents | 否 | gzdecode() |
curl 示例
# 正确写法:加 --compressed,由 curl 自动解压 curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/today"
Python urllib 示例(这类最容易静默失败)
import urllib.request, gzip, json req = urllib.request.Request(url, headers={ "X-API-Token": TK, "Accept-Encoding": "gzip", }) r = urllib.request.urlopen(req) raw = r.read() if r.headers.get("Content-Encoding") == "gzip": raw = gzip.decompress(raw) data = json.loads(raw)
自检方法:正常响应是 JSON(以 { 或 [ 开头)。
若拿到文件头为 1F 8B 的二进制,或抛 UnicodeDecodeError /
JSONDecodeError,就是没有解压。
接口总览
下表为全部对外数据接口(共 44 条),均以 GET 调用;路径单元格在窄屏自动折行。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | | 联赛数字 ID → 中文短名映射(单一真源) |
| GET | | 加工层单场详情,含时间序列曲线 |
| GET | | 加工层赛事列表,date 两种格式均可 |
| GET | | 无参探活,无需鉴权,返回固定 JSON |
| GET | | 查询自身套餐、配额与到期时间 |
| GET | | 联赛积分榜,需带 league 或 league_id |
| GET | | 积分榜并附带 xG 口径字段 |
| GET | | 今日赛事列表(含 league_id) |
| GET | | 历史赛果库(永久归档 2020→今) |
| GET | | 赔率来源(公司)列表 |
| GET | | 某场比赛的转播信息 |
| GET | | 教练详情(战绩 / 执教履历 / 近期比赛) |
| GET | | 按日赛程列表,date 支持 dd/mm/yyyy 与 YYYY-MM-DD |
| GET | | 该场逐分钟事件(进球 / 红黄牌 / 换人) |
| GET | | 首选口径 xG 预期(与 /matches 同源 ID) |
| GET | | 该场历史交锋记录 |
| GET | | 某日全部比赛聚合,inline 三档可选 |
| GET | | 全部伤停信息汇总 |
| GET | | 该场伤停列表 |
| GET | | 按联赛 ID 取联赛详情 |
| GET | | 该场阵容(阵型与首发 / 替补) |
| GET | | 按教练 ID 取教练信息 |
| GET | | 单场基础信息行(联赛 / 队名 / 比分) |
| GET | | 收盘线价值(CLV)三路数值 |
| GET | | 单场完整数据(13 张子表装配) |
| GET | | 该场赔率历史记录 |
| GET | | 单场射门落点与平均站位 |
| GET | | 该场技术统计(含半场 xG) |
| GET | | 赛事列表(快照层,支持 date 与分页) |
| GET | | 单场赔率(含封盘标记) |
| GET | | 各公司赔率时间序列 |
| GET | | 多市场赔率 |
| GET | | 批量取多场多市场赔率,省配额 |
| GET | | 按球员 ID 取球员信息 |
| GET | | 按裁判 ID 取裁判信息 |
| GET | | 按队名子串检索比赛,最多 50 条 |
| GET | | 赛季列表 |
| GET | | 历史每日快照(筛选 + 分页) |
| GET | | 球队近期 xG 形态,n 默认 10 |
| GET | | 按球队名取球队信息 |
| GET | | 按 team_id 取球队信息 |
| GET | | 球队赛程,最多 30 行 |
| GET | | 球场 / 场馆列表 |
| GET | | 按场馆 ID 取场馆详情 |
另有为客户端优化的赛事专项接口,如需了解请联系运营方。
1. 鉴权
所有数据接口需携带有效 Token,二选一:
| 方式 | 请求头 | 示例 |
|---|---|---|
| 建议 | X-API-Token | X-API-Token: <你的Token> |
| 兼容 | Authorization | Authorization: Bearer <你的Token> |
缺失或无效 Token 返回 401,响应体内会提示使用 X-API-Token 头。
每次请求计 1 次配额(quantum:按账号 plan 的 quota_daily)。用聚合接口可显著降低请求数。
唯一例外:GET /api/profile(查看自身余额/到期)不计次,可放心轮询做余额提醒。
2. 日期与时区口径
时区统一为 Asia/Shanghai(北京时间 / UTC+8)。不同端点接受的日期入参格式并不一致,务必按下表选择。按 date= 查询的列表端点已统一为双格式兼容,格式写错会拿到 400,不会再静默返回空集。
| 端点 | 接受的 date 格式 | 非法格式的表现 |
|---|---|---|
/history/{date} | 仅 ISO YYYY-MM-DD(2026-9-1 这类非零填充亦接受) | 单段非法值(如 abc、20260901)→ 400 invalid date; expected YYYY-MM-DD (Asia/Shanghai);带斜杠的 DD/MM/YYYY(如 01/09/2026)因不匹配路由 → 404 |
/matches?date= | ISO 与 DD/MM/YYYY 均接受 | 格式非法(如 abc)或日期不存在(如 2026-13-45)→ 400;省略 date 时不过滤 |
/day_fixtures?date= | ISO 与 DD/MM/YYYY 均接受(必填) | 缺失 / 为空 / 格式非法 → 400 |
/snapshot/history?date= | ISO 与 DD/MM/YYYY 均接受 | 省略 date 时返回默认窗口 |
/archive/matches?date= | ISO 与 DD/MM/YYYY 均接受 | —(亦可用 year / month) |
响应中的日期字段(勿混淆)
| 字段 | 格式 | 说明 |
|---|---|---|
行内 date | DD/MM/YYYY | 如 01/09/2026(上海日期);/history、/matches、/snapshot/history、/archive/matches 的行均如此 |
顶层 data.date | YYYY-MM-DD(ISO) | 仅 /history/{date} 返回 |
event_date | 按端点不同 | /history 内为上海日期 YYYY-MM-DD;/archive/matches 内为 UTC ISO 时间戳(如 2020-12-30T16:00:00+00:00,可能比行内 date 早一天) |
最易踩的坑:/history/{date} 传 DD/MM/YYYY 直接 404 —— 它是路径匹配,不做格式转换。其余按 date= 查询的列表端点已统一双格式兼容;格式非法会返回 400 并带上原因,不会再给你一个「看起来正常」的 count=0。
3. 历史/当日聚合 GET 需鉴权
GET /history/{date}?inline=none|summary|full
一次返回某日全部比赛,消除"K 场比赛 = 1+K 次调用"。默认 inline=summary。
三档为严格包含关系:none ⊂ summary ⊂ full。字段差异如下:
| 字段 | none | summary(默认) | full |
|---|---|---|---|
基础列表字段(event_id/联赛/球队/时间/状态/比分/半场/中文名等) | ✔ | ✔ | ✔ |
events_count(事件计数) | — | ✔ | ✔ |
match_full(单场完整详情,内容同 /match_full/{event_id},13 张子表装配) | — | — | ✔ |
即:summary 在 none 基础上增加 events_count;full 在 summary 基础上再内联 match_full,因此 full 同样带 events_count。
请求示例
# 某日全部比赛(默认摘要) curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/history/2026-09-01" # 某日全部比赛 + 每场完整详情(一次取全,慎用大响应) curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/history/2026-09-01?inline=full"
响应结构(字段示意,示例值均为虚构)
{
"code": 0,
"message": "ok",
"data": {
"date": "2026-09-01",
"tz": "Asia/Shanghai",
"inline": "summary",
"count": 42,
"total": 42,
"filtered_empty": 0,
"matches": [ { "event_id": 100001, "league_zh": "意甲", "home_team_zh": "示例队 A", "away_team_zh": "示例队 B", "date": "01/09/2026", "home_score": 0, "away_score": 4, "status": "ft", "events_count": 20 }, ... ]
}
}
上例只示字段结构与层级关系,不是任何一场真实比赛;event_id、队名、比分均为虚构占位值。真实数据须带 Token 调用取得。
新增响应字段
| 字段 | 位置 | 说明 |
|---|---|---|
total | data.total | 该日真实总行数(本端点不分页,故通常与 count 相等)。 |
filtered_empty | data.filtered_empty | 被过滤掉的"空壳行"数量(这些行联赛名与两队名全为空),不计入 matches;count 恒为实际返回条数。 |
行键集契约:/history/{date} 的 matches[] 每行键集完全一致;某行若无对应原始数据,该键仍存在但值为 null。其中 league / home_team / away_team 在无原始值时以 league_zh / home_team_zh / away_team_zh 回填,因此任意一行都可直接用这三个字段,不会再出现"某行缺键"。
4. 单场完整数据 GET 需鉴权
GET /match_full/{event_id}
返回单场装配好的全部数据:基础信息 + 比分/半场 + 赔率(欧赔/亚盘)+ 阵容 + 伤停 + 事件 + 统计(含 xG)+ H2H 等。
响应顶层另含 home_team_id / away_team_id(整数),可直接用于 /teams/{team_id} 与 /teams/{team_id}/fixtures,无需另调其它接口。
球队块:顶层 home_team / away_team 是球队名(字符串),home_team_zh / away_team_zh 为中文名;另有 team_home / team_away 两个对象(各 6 键:name 队名 / country 所属国家 / logo 队徽(可能为空串)/ venue 主场 / coach 主教练姓名(未采集到为空串)/ coach_info 主教练档案对象(name / coach_id / nationality / preferred_formation / tactical_profile / matches_total / win_pct,键恒定存在,无数据时为空串或 null)),适合直接渲染球队卡。要拿整队球员请改用 /teams/{team_id}/squad。
近期战绩 recent_results
主客队各自的近期已完赛战绩。键恒存在:取不到数据时给空 matches + reason,既不省略键,也不会因为这一块让详情接口 500。
口径与 GET /team_recent/{team_id} 完全同源(同一个取数函数、同 365 天窗口、同友谊赛排除规则),所以"详情页里的近期状态"与"直接调该接口"不会出现两套数字。
| 字段 | 类型 | 说明 |
|---|---|---|
limit | int | 每侧取几场,当前 8。 |
days | int | 时间窗(天),当前 365,只统计窗内已完赛。 |
include_friendly | bool | 是否含友谊赛,当前 false(默认排除)。被排除的场次数见各队的 excluded_friendly。 |
home / away | object | 主 / 客队的战绩对象,结构见下一张表。 |
home 与 away 的对象结构:
| 字段 | 类型 | 说明 |
|---|---|---|
found | bool | 是否取到该队战绩。 |
team_id / team_name / team_known | int / string / bool | 球队 ID、中文名、是否在球队表内。 |
count | int | 实际返回场次(≤ limit)。 |
excluded_friendly | int | 因 include_friendly:false 被排除的友谊赛场次。 |
reason | string | 取不到时的原因;正常为空串。 |
summary | object | played / wins / draws / losses / goals_for / goals_against / win_pct(百分数,如 37.5)。 |
matches | array | 逐场明细,按时间倒序,见下。 |
matches[] 每项字段:event_id(可用 /match_full/{event_id} 取该场详情)、event_date(UTC ISO)、date(YYYY-MM-DD)、time、home_team / away_team(中文名)、home_score / away_score、score(如 "2-0")、localteamscore / visitorteamscore、status / status_raw / is_finished、league(中文联赛名)、team_side(home / away)、is_home、venue、goals_for / goals_against(从该队视角)、result(win / draw / loss,该队视角)。
渲染胜平负请直接用 result,或 goals_for / goals_against。不要拿 home_score 与 away_score 自己比大小 —— 那是主客队视角,客场比赛会把输赢判反。
分庄家赔率:odds_by_bookmaker 是 {庄家: {市场: {选项: 赔率}}} 的三层结构,市场名已中文化(如 胜平负 / 亚盘),选项名形如 主队 / 平局 / 客队(亚盘市场为带盘口的队伍名)。不同庄家返回的市场不完全相同,按需取用;聚合后的欧赔看 odds,多市场汇总看 odds_multi。
money 是预留字段,当前恒为空对象 {},可忽略。
无效 event_id 返回 404 {"detail":"match not found"}(不再返回 200 {"found": false});若 event_id 不是整数(如 /match_full/abc)则返回 422。
示例
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/match_full/100002"
提示:用 /history/{date}?inline=full 可一次取某日全部场次的完整数据,避免逐场调用额外消耗额度。
该端点响应内联的 xG 相关字段(expected_xg / historical_odds / match_stats / odds_available)详见 第 7 节 xG 预期。
5. 比赛列表 GET 需鉴权
6. 联赛 ID 与中文名 GET 需鉴权
GET /api/leagues
返回全部联赛的 数字 ID → 中文名 映射,用于把比赛行里的 league_id 还原为可读联赛名。
响应结构
{
"leagues": {
"1234": "西甲",
"1235": "意甲",
...
}
}
键为联赛数字 ID(字符串形式),值为对应中文短名。该 ID 与比赛响应中的 league_id 同源,可直接 join。该映射现以 leagues 表为单一真源,共 91 个键。
行内新增 league_id 字段
| 端点 | 新增字段 | 说明 |
|---|---|---|
/matches | league_id(整数)、league_zh(中文名) | 可直接用 league_id 关联 /api/leagues。 |
/api/today | league_id(整数) | — |
/match_full/{event_id} | league_id(整数) | — |
/history/{date} | league_id(整数) | — |
league_id=0 表示该联赛尚未纳入映射表(未知 / 无联赛归类),不要把它当成某个具体联赛;此时客户应回退用 league_zh 展示。完整口径详见 第 14 节。
GET /leagues/{league_id} 联赛详情
按联赛 ID 取详情:
{
"league_id": 1234,
"name": "La Liga",
"country": "Spain",
"season": "2025/2026",
"standings": [ ... ],
"updated_at": "2026-10-10T12:00:00+08:00",
"name_zh": "西甲"
}
该响应不再返回 logo 字段(上游数据源未提供,此前恒为空字符串);/teams/{team_id} 同理。历史客户端请勿依赖该键,详见 第 14 节。
示例
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/leagues" curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/leagues/1234"
7. xG 预期进球 GET 需鉴权
系统对 xG(预期进球)共有 三种口径,三者的数据来源与 event_id 空间互不相同。其中 /match_xg/{event_id} 已于 2026-11-04 下线(请求返回 404,原因与替代方案见 第 13 节),当前实际可用的是另两种。
| 端点 | 口径 | event_id | 状态 |
|---|---|---|---|
/expected_xg/{event_id} | 基于双方近期赛后 xG 形态派生 | 与 /matches 同源 | 在用(首选) |
/match_xg/{event_id} | 独立历史 xG 库(Understat 口径) | 独立空间,不互通 | 已下线 |
/team_xg_form/{team} | 球队近期 xG 形态 | 按队名 / team_id | 在用 |
GET /expected_xg/{event_id} — 首选口径
基于双方近期赛后 xG 形态派生,按比赛 event_id(与 /matches 同源)取,返回中文队名。
{
"found": true,
"event_id": 100001,
"home_team": "示例队 A",
"away_team": "示例队 B",
"expected_xg": {
"home": 1.12, "away": 1.68,
"home_h1": 0.48, "away_h1": 0.72,
"home_h2": 0.64, "away_h2": 0.96
},
"home_form": { ... },
"away_form": { ... }
}
历史场次 / 未来场次在样本不足时返回 {"found": false},此时不含 expected_xg / home_form / away_form 字段。
GET /match_xg/{event_id} — 独立历史 xG 库(Understat 口径)已于 2026-11-04 下线
该端点已于 2026-11-04 下线,请求返回 404 {"detail":"Not Found"},不可再调用。下线原因:该库的 event_id 与本站赛事 ID 属两套体系、无交集,用本站 id 查询恒为 {"found": false}。取 xG 请改用 /expected_xg/{event_id}(与 /matches 同源)或 /team_xg_form/{team}。
下方字段表仅作历史数据说明保留,供此前已导出过该数据集的调用方对照字段含义;新接入请勿依赖。
| 字段 | 说明 |
|---|---|
event_id | 该库自己的 ID(与主接口不互通) |
league | 联赛码,英文:EPL / La_liga / Serie_A / Ligue_1 / Bundesliga |
season | 赛季,仅 2021–2025 |
datetime | 比赛时间 |
home_team / away_team | 队名,英文 |
home_goals / away_goals | 实际进球数 |
home_xg / away_xg / total_xg | 主客队 xG 及合计 |
xg_p_h / xg_p_d / xg_p_a | 由 xG 派生的主/平/客分量 |
us_forecast_w / us_forecast_d / us_forecast_l | 该库给出的胜/平/负分量 |
found | 是否命中记录 |
队名为英文、联赛码为英文,赛季仅覆盖 2021–2025。
GET /team_xg_form/{team}?n=10 — 球队近期 xG 形态
team 可传 中文队名(需 URL 编码)或 team_id(数字)。n 为取样场数,默认 10。
{
"n": 10,
"xg_for_avg": 1.42,
"xg_against_avg": 1.03,
"xg_for_h1_avg": 0.61,
"xg_against_h1_avg": 0.44,
"xg_for_h2_avg": 0.81,
"xg_against_h2_avg": 0.59,
"home_xg_for_avg": 1.66,
"away_xg_for_avg": 1.18,
"team": "示例队 B"
}
/match_full/{event_id} 内联的 xG 相关字段
| 字段 | 说明 |
|---|---|
expected_xg | 同 /expected_xg/{event_id} 的结果(按 /matches 的 event_id)。 |
historical_xg | 已于 2026-11-01 从本响应摘除:历史 xG 数据集(Understat)的 event_id 与本站赛事 ID 属两套体系、无交集,恒查不到数据。对应独立端点 /match_xg/{event_id} 亦已于 2026-11-04 下线。 |
historical_odds | 历史赔率段。 |
match_stats | 比赛统计,含半场 xG。 |
odds_available | 该场是否有可用赔率的标记。 |
curl 示例
# 1) 首选口径 xG:用 /matches 同源的 event_id curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/expected_xg/100001" # 2) 球队近期 xG 形态:中文队名需 URL 编码,也可直接传 team_id curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/team_xg_form/100001?n=10" # 也可直接传 team_id: curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/team_xg_form/1234?n=10"
8. 赔率与 CLV GET 需鉴权
GET /match_clv/{event_id} — 收盘线价值(CLV)
返回收盘线价值差(CLV)数据。
{
"found": true,
"event_id": 100001,
"clv": {
"clv_home": 0.00042,
"clv_draw": -0.00011,
"clv_away": 0.00095
},
"has_open": 1,
"samples_count": 37,
"updated_at": "2026-10-10T18:00:00+08:00"
}
| 字段 | 说明 |
|---|---|
found | 是否命中记录。 |
clv.clv_home / clv.clv_draw / clv.clv_away | 主 / 平 / 客三路的 CLV 数值。 |
has_open | 0 表示仅 1 个采样点(无开盘参照)。 |
samples_count | 采样点数。 |
updated_at | 更新时间。 |
口径:CLV 为同一场比赛「开盘点」与「最新点」的隐含概率差;开盘点取该场首个三项赔率(主/平/客)齐全的采样点。clv_home、clv_draw、clv_away 分别对应主、平、客三路:该路赔率下降(更被看好 / 变热)为正值,上升为负值;量级约 1e-4 ~ 1e-3,无百分比单位。has_open=1 表示已有 2 个及以上有效采样点、可算走势;has_open=0 表示仅 1 个采样点,此时 clv 恒为 0。
覆盖范围:仅赛前窗口内(未开赛)且已采集到赔率的场次(当前约覆盖 95%);窗口外或未采集赔率的场次一律 found=false。数据随后台整理线程每 5 分钟全量刷新一次。同一场次的 CLV 也内联在 /match_clv/{event_id} 的 clv 段中。
GET /odds/{event_id} — 单场赔率
响应恒定含 odds_closed / odds_closed_reason 两个字段,详见 第 10 节「历史数据端点」。
GET /odds_multi/{event_id} — 多市场赔率
{
"event_id": 100001,
"markets": {
"1x2": [
{ "bookmaker": "bet365", "outcome": "H", "odds": 2.10, "market_zh": "胜平负", "outcome_zh": "主胜" },
...
],
...
}
}
列表每项含 bookmaker / outcome / odds / market_zh / outcome_zh。
GET /odds_curve/{event_id}?bookmaker=&market=&limit= — 各公司赔率时间序列
{
"event_id": 100001,
"companies": {
"bet365": {
"1x2": {
"H": [ { "ts": "2026-09-01T10:00:00+08:00", "odds": 2.12 }, ... ]
}
}
},
"count": 128
}
结构为 companies → 公司 → 市场 → OUTCOME → [{ts, odds}, ...]。
GET /match_odds_hist/{event_id} — 赔率历史
返回该场赔率的历史记录。
9. 技术统计
本节端点需鉴权;示例中的 ID 与数值均为虚构,仅示字段结构。
GET /match_stats/{event_id} — 技术统计
{
"event_id": 100001,
"stats": [ ... ]
}
10. 历史数据端点与响应新增字段
GET /snapshot/history(历史每日快照)
参数:date / month / league / team / status / limit / offset。date 同时接受 YYYY-MM-DD 与 DD/MM/YYYY。
响应新增分页字段 total / limit / offset / has_more;count 仍等于本页条数。
GET /archive/matches(历史赛果库,永久归档 2020→今)
参数:year / month / league / team / team_id / date / status / limit / offset。
响应新增上述四个分页字段;count 仍等于本页条数。
归档行的 league 为中文联赛名,home_team / away_team 为原始队名(2020–2025 归档行队名全为英文原名,2026 部分行如俱乐部友谊赛已是中文);响应不含任何 *_zh 字段,这不是接口故障。
分页字段用法(/snapshot/history 与 /archive/matches)
| 字段 | 说明 |
|---|---|
count | 本次返回条数(本页条数),不是总行数。 |
total | 过滤条件下的真实总行数。 |
limit | 本次生效的每页条数上限。 |
offset | 本次生效的偏移量。 |
has_more | 判断是否还有下一页请用它:true 表示 offset + len(rows) < total。 |
不要用 count 判断是否翻完页;count 恒等于本页条数。本类端点 limit 上限为 1000。
GET /odds/{event_id}(单场赔率)
响应恒定新增两个字段:
| 字段 | 类型 | 说明 |
|---|---|---|
odds_closed | bool | 赔率是否已封盘;比赛已结束时为 true。 |
odds_closed_reason | string | null | 封盘原因;未封盘为 null,已完赛时为"比赛已结束,赔率在开赛时刻冻结"。 |
11. 其它端点一览
以下为辅助 / 参考类端点(均需鉴权,除另有说明外)。
| 端点 | 说明 |
|---|---|
GET /referees/{referee_id} | 按裁判 ID 取裁判信息。 |
GET /injuries/all | 全部伤停信息汇总。 |
GET /bookmakers | 赔率来源(公司)列表。 |
GET /seasons | 赛季列表。 |
GET /venues | 球场 / 场馆列表。 |
GET /managers/{manager_id} | 按教练 ID 取教练信息。字段见 第 16 节。 |
GET /coaches/{coach_id} | 教练详情:档案 + 战绩 + 执教履历 + 近期比赛。字段见 第 16 节。 |
GET /broadcasts/{event_id} | 某场比赛的转播信息。 |
GET /teams/{team_id} | 按 team_id 取球队信息。 |
GET /teams/name/{name} | 按球队名取球队信息。 |
GET /players/{player_id} | 按球员 ID 取球员信息。字段见 第 16 节。 |
GET /snapshot/history | 历史每日快照,见 第 10 节。 |
GET /archive/matches | 历史赛果库(永久归档),见 第 10 节。 |
12. 错误码
| 状态码 | 含义 | 说明 |
|---|---|---|
| 200 | 成功 | — |
| 400 | 参数错误 | 如 /history/{date} 日期为单段非 ISO({"detail":"invalid date; expected YYYY-MM-DD (Asia/Shanghai)"})、inline 取值非法 |
| 401 | 未授权 | 缺 Token → {"detail":"缺少 API Token"};无效 Token → {"detail":"无效的 API Token"} |
| 403 | 禁止访问 | /status 与 /api/status 为服务端专用,仅本机(127.0.0.1)可访问;非本机访问恒返回 403 {"detail":"access restricted to server only"}(本机访问则返回 200,且无需 Token) |
| 404 | 不存在 | 无效 event_id({"detail":"match not found"})、已下架接口、无权限的套餐受限接口,或 /history/{date} 的 {date} 含斜杠等不匹配路由 |
| 422 | 参数类型错误 | FastAPI 参数校验失败,如 /match_full/abc、/matches?limit=abc;响应为 {"detail":[{"type":"int_parsing", ...}]}。路径/查询中的整数超出有符号 64 位范围(±2^63)时同样返回 422(而非 500) |
| 429 | 超限 | 配额(次数/周期额度)已用尽,或短时间并发过高被临时限流 |
401 既可能是未带 Token,也可能是 Token 无效,请按响应体 detail 区分。
/matches?limit 超过上限会被钳制为上限值(不报错)。
13. 已下架接口
以下接口已下架(返回 404 {"detail":"Not Found"}),请改用对应替代方案:
| 已下架 | 替代 |
|---|---|
/api/live 404 | 改用 /matches?live_only=1 或 /api/today |
/live_scores 404 | 改用 /matches?live_only=1 |
/stats/{event_id} 404 | 改用 /match_stats/{event_id} 或 /match_full/{event_id} 的 stats 段 |
/polymarket/{event_id} 404 | 改用 /match_full/{event_id} 的 polymarket 段(该数据源已暂停采集,新场次该段可能为空) |
/referees/match/{event_id} 404 | 改用 /match_full/{event_id} 的 referee 段,或 /referees/{referee_id} |
/match_detail 404 | 按赛事 ID 取单场用 /match_full/{event_id};按日检索用 /matches?date= |
/sync/pull · /sync/status 404 | 数据同步内部工具,不对外提供 |
/history(不带日期) 404 | 改用 /history/{date}(须带 ISO 日期) |
/match_xg/{event_id} 404 | 2026-11-04 下线:数据源(独立历史 xG 库)的 event_id 与本站赛事 ID 属两套体系、无交集,恒无数据。取 xG 改用 /expected_xg/{event_id} 或 /team_xg_form/{team} |
本版恢复上线的接口(2026-10-10)
下列接口此前临时下架,现已恢复可用(均需鉴权)。它们各返回单场的一类数据,需要单类数据时可直接替代 /match_full/{event_id} 的对应段,减少响应体积:
| 已恢复接口 | 说明 |
|---|---|
GET /match/{event_id} | 单场基础信息行(联赛 / 队名 / 比分 / 状态等)。 |
GET /lineups/{event_id} | 该场阵容(含阵型与首发 / 替补)。 |
GET /injuries/{event_id} | 该场伤停列表。 |
GET /events/{event_id} | 该场逐分钟事件(进球 / 红黄牌 / 换人 / VAR 等)。 |
GET /h2h/{event_id} | 该场历史交锋记录。 |
GET /day_fixtures?date=dd/mm/yyyy | 按日赛程列表(date 支持 dd/mm/yyyy 与 YYYY-MM-DD;date 必填,缺失或非法返回 400)。 |
GET /search?q=<关键词> | 按队名子串检索比赛,返回匹配总数与列表(列表最多 50 条)。 |
已恢复接口返回空数组 / 空对象(如 {"event_id": 123, "injuries": []})表示该场暂无此类数据,不是接口故障;/events 对未开赛场次通常为空。
14. 字段口径变更说明 GET 需鉴权
本节汇总本版对外契约的字段口径变更(分 P2、P3 两批上线,共 6 个子节)。各端点正文处亦已同步标注,交叉引用见对应章节。
15.1 联赛字段 league_id 与 league_zh(/matches、/api/today、/match_full)
比赛对象每行含下列联赛字段:
| 字段 | 类型 | 说明 |
|---|---|---|
league_id | int | 与 leagues.league_id 同源,可用于跨接口对齐。 |
league_zh | string | 联赛中文短名(如「西甲」「英超」)。 |
league_id = 0 表示该联赛尚未纳入映射表,客户应回退用 league_zh 展示,不要把 0 当成某个具体联赛。
与 /api/leagues 的关系:该端点返回 {联赛id: 中文短名} 映射,现以 leagues 表为单一真源(91 个键);比赛行的 league_id 可直接 join 该映射。
curl 示例
# 取某日比赛列表,行内同时含 league_id 与 league_zh curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/matches?date=01/09/2026" # 取联赛映射表(单一真源),用于把 league_id 还原为中文短名 curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/leagues"
15.3 /leagues/{league_id} 与 /teams/{team_id} 不再返回 logo
两个端点的响应不再返回 logo 字段:上游数据源未提供该字段,此前恒为空字符串。
移除为最终状态,历史客户端请勿依赖 logo 键;读取到该键缺失属预期行为,不是接口故障。
curl 示例
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/leagues/1234" curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/teams/1234"
15.4 开球时间字段 time 与 time_known
该口径对 /matches、/api/today、/match_full 一致适用;P3 起,/snapshot/history 与 /archive/matches 亦对齐同一口径(此前这两个端点直接透传 storage 原始行、未做归一):
| 字段 | 类型 | 说明 |
|---|---|---|
time | string | null | 开球时间;上游未提供时为 null。 |
time_known | bool | false = 时间未知;true = 时间可信。 |
旧版本在时间未知时会返回字符串 "00:00";客户不应再把 "00:00" 当作真实午夜场解析。请改用 time_known 判断时间是否可信:time_known=false 时忽略 time。
当前状态(P3):/snapshot/history?limit=1000 的占位值 00:00 由 72 行降为 0 行、/archive/matches?limit=1000 由 49 行降为 0 行;两者均 1000/1000 行带 time_known。其 total / limit / offset / has_more 分页契约未变(本次只改字段值,不增删行)。
curl 示例
# 取单场完整数据,检查 time 与 time_known curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/match_full/100002"
15.5 空壳行剔除(/matches)
/matches 会剔除「空壳行」。判据与 /history/{date} 的既有判据一致,但剔除动作发生在 SQL 查询层(storage.get_snapshots(..., exclude_empty=True)),因此不占用分页名额。
P4 起 filtered_empty 已从 /matches 响应中移除,请勿再依赖该字段。
| 字段 | 类型 | 说明 |
|---|---|---|
count | int | 语义为本页返回条数(已剔除空壳行之后)。 |
空壳行判据(保守):league_zh、home_team_zh、away_team_zh 三字段全部为空 / 缺失的行才剔除;只缺其中一个字段的行一律保留(当前有 72 行「有队名但缺 league_zh」被保留)。
当前规模:/matches?limit=6000 → count=4735(剔除前为 4969 行,共剔除 234 行)。这 234 行并非无用记录:它们缺少联赛名 / 队名 / 日期等身份列,但 lineups(阵容)/ h2h(交锋史)/ injuries(伤停)/ odds(赔率)等业务数据完整,且 /match_full/{event_id} 仍可取到。本次仅将其隔离出列表,未删除任何数据。
分页保证(P4 修复):此前剔除发生在分页切片之后,会令非末页也变短(limit=1000 时第 2 / 3 页只有 903 / 863 行),客户端若按「遇短页即停」分页会漏取。改为 SQL 下推后,除末页外每页恒为 limit 条:offset 0 / 1000 / 2000 / 3000 各页页长均为 1000,offset=4000 末页为 735;全库 4735 行按 limit=1000 朴素分页可完整取回,不会漏行。
/matches 响应顶层键:快照分支为 count / matches / odds_coverage / snapshot;回退分支(date 传 ISO 且未命中)为 count / matches / odds_coverage。请将 snapshot 视为可选键——它仅标识该响应来自快照层。
curl 示例
# 大 limit 拉取;空壳行已在 SQL 层剔除,分页页长恒定 curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/matches?date=01/09/2026&limit=6000"
15.6 /api/today 新增 count
/api/today 响应顶层新增 count,等于 len(matches),与 /matches 契约对称,客户端无需再自行 len()。
| 字段 | 类型 | 说明 |
|---|---|---|
count | int | 返回场次条数,等于 len(matches)。 |
当前:count=411,等于 len(matches)。
响应当前顶层键:count / date / matches / odds_coverage / source。
curl 示例
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/today"
15. 卡密激活
激活与续期都在兑换页完成,本文档不提供调用方式:打开 卡密激活页,填入卡密提交,页面会显示一串 API Token。
激活页是公开页面,不需要 Token;拿到 Token 后按第 1 节的方式放进请求头。卡密若提示已被使用或已失效,请联系运营方。
16. 补充接口
下列 12 条接口此前未写入文档或只列了一句话,本版补齐。均为 GET,除 /api/ping 外均需鉴权;示例中的 ID、队名与数值均为虚构,仅示字段结构。
GET /api/ping — 无参探活
无参数、无需鉴权,返回 {"ok":true},用于确认服务可达。
curl --compressed "https://huhuan.hb.cn/api/ping"
GET /api/profile — 查看自身授权
需鉴权。返回当前 Token 的套餐、用量与到期时间,可用于确认 Token 是否有效。
本端点不计入调用次数(不扣配额、不影响 usage_live 口径)。可以随意轮询做余额提醒,不必担心把额度查没了。
| 字段 | 类型 | 说明 |
|---|---|---|
plan | string | 套餐档位;pack 表示「次数包」。 |
status | string | 账号状态。 |
created_at | number | 创建时间(Unix 秒)。 |
expires_at | number | null | 到期时间(Unix 秒);null 表示永久。 |
expires_str | string | 到期时间的可读文本;永久时为「永久」。 |
quota_daily | number | 每日调用上限;0 表示不限。 |
quota_total | number | 周期(30 天)额度上限;0 表示不限。 |
quota_lifetime | number | 次数包专用:终身总次数;0 表示当前账号不是次数包。 |
quota_lifetime_left | number | null | 剩余次数;非次数包为 null(注意与「剩余 0 次」区分)。 |
quota_lifetime_used | number | null | 已用次数;非次数包为 null。 |
quota_lifetime_pct | number | null | 已用百分比(0–100)。 |
quota_exhausted | bool | 次数包是否已用尽(此时数据接口返回 429)。 |
quota_low | bool | 次数是否告急(剩余 ≤ 10% 或 ≤ 200 次)。 |
usage_live | bool | 用量数字是否为服务端实时值。false 表示取的是最近一次落库值,最多滞后 usage_lag_max 秒(默认 15)。 |
usage_lag_max | number | 落库周期上限(秒)。 |
server_time | number | 服务端当前时间(Unix 秒)。 |
used_today | number | 今日已用次数;剩余 = quota_daily - used_today(quota_daily=0 时不适用)。 |
total_used | number | 累计已用次数(终身)。 |
max_concurrent | number | 并发上限。 |
is_expired | bool | 是否已过期。 |
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/profile"
GET /api/matches?date= — 加工层赛事列表
与第 5 节的 /matches 是两套列表:本端点数据来自加工表 match_snapshots,与 /api/match/{match_id} 同源。date 同时接受 YYYY-MM-DD 与 DD/MM/YYYY;省略 date 时返回近几天窗口。
每行含 league_zh / home_team_zh / away_team_zh / date / time / status_zh / home_score / away_score / minute / priority / is_major,并批量注入最佳赔率 home_win / draw / away_win。
GET /api/match/{match_id} — 加工层单场详情
match_id 兼容数字 event_id(如 100001)与文本 ID(如 e100001)。响应顶层为 event_id / match_id / detail / series;series 为赔率与实时状态的时间序列曲线。
无法解析的 ID 返回 404 {"detail":"match not found"}。模型相关字段已从 detail 中剥离。
GET /api/standings?league=|league_id= — 联赛积分榜
两个参数二选一必填,都不传返回 400 {"detail":"缺少 league 或 league_id 参数"}。league 为中文名(如 英超),league_id 为数字(服务端内部反查中文名)。响应为积分榜行数组,另附 updated_at。
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/standings?league=%E8%8B%B1%E8%B6%85"
GET /api/standings_xg?league= — 积分榜(附 xG 口径)
在积分榜基础上追加 xG 相关列。每行只输出下列固定字段,上游新增的脏字段不会透传:
| 字段 | 类型 | 说明 |
|---|---|---|
position team_id played won drawn lost gf ga gd pts | int | 排名 / 球队 ID / 场次 / 胜 / 平 / 负 / 进球 / 失球 / 净胜球 / 积分。 |
xgf xga xgd | float | xG 口径的进球、失球与净差值。 |
xg_games | int | 参与 xG 计算的场次数。 |
form | string | 近期战绩串。 |
live | bool | 是否为进行中的实时口径。 |
数值解析失败的字段返回 null,不会因此报错。
GET /match_shotmap/{event_id} — 射门图与平均站位
未采集过的场次返回空数组且 meta 为 null(不报 404),便于前端直接判断。
{
"event_id": 100001,
"shots": [ ... ],
"average_positions": [ ... ],
"meta": { "has_data": 1, "shot_count": 24,
"avg_pos_count": 22, "fetched_at": 1760000000 }
}
shots[] 字段:seq / minute / added / goal_x goal_y goal_z / from_x from_y from_z / block_x block_y block_z / xg / xgot / xg_is_est / is_home / shot_type / sit / body / gml / gtype / player_id。
average_positions[] 字段:player_id / is_home / shirt_no / player_name / pos / x / y。
GET /odds_multi_batch?ids= — 批量多市场赔率
单次 HTTP 取多场的多市场赔率,替代逐场调用 /odds_multi/{event_id} 的 N+1 轮询,可显著降低额度消耗。
ids 为逗号分隔的整数列表(如 100001,100002);非整数片段会被静默忽略。count 为实际返回的场次数,markets 为 {event_id: [赔率项...]}。
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/odds_multi_batch?ids=100001,100002"
GET /teams/{team_id}/fixtures — 球队赛程
按 team_id 取赛程,最多返回 30 行,按 date、time 升序。无数据时返回 {"found": false, "team_id": ..., "fixtures": []}。
fixtures[] 字段:id / team_id / team_name / event_id / date / time / opponent / home / league / status / score / updated_at。
status 取值:notstarted(未开赛)/ inprogress(进行中)/ finished(完场)/ postponed(延期)。另有少量历史行残留 1st_half / halftime / 2nd_half,属早期写入后未同步终态,不可据其判断比赛正在进行;判断是否完场请以 score 非空或 date 已过去为准。
league 目前恒为空字符串(保留字段位、尚未回填),不是接口故障;需要联赛名请改用 /matches 或 /match_full。
GET /venues/{venue_id} — 场馆详情
按 venue_id 取场馆,未命中返回 {"found": false}(不是 404)。命中时返回 venue_id / name / city / country / capacity / surface / home_team / updated_at;列表用第 11 节的 /venues。
GET /players/{player_id} — 球员档案
按 player_id 取球员完整档案;未命中返回 {"found": false}(不是 404)。上游缺失的数值字段返回 null,不报错。
| 字段 | 类型 | 说明 |
|---|---|---|
player_id | int | 球员 ID。 |
name short_name | string | 全名 / 简称。 |
name_zh short_name_zh | string | 中文名。有映射时返回中文,无映射时回落英文原名(不是空串);前端展示优先用它。 |
nationality | string | 国籍。 |
birthdate | string | 出生日期 YYYY-MM-DD。 |
height weight | number | null | 身高(厘米)/ 体重(公斤)。 |
position specific_position | string | 位置组(如 F)/ 具体位置(如 ST)。 |
preferred_foot | string | 惯用脚(L / R)。 |
market_value | number | null | 身价,单位欧元。如 240000000.0 即 2.4 亿欧。 |
wage_eur_annual | number | null | 年薪,单位欧元。 |
contract_until | string | null | 合同到期日 YYYY-MM-DD。 |
rating | number | null | 能力评分。 |
potential injury_risk | string | null | 成长评价 / 伤病风险标签(上游原文枚举,未翻译)。 |
current_team_id national_team_id | int | null | 所属俱乐部 / 国家队 ID,可用第 11 节 /teams/{team_id} 展开队名。 |
photo | string | 头像地址,可能为空串。 |
updated_at | number | 本行最后更新时间(Unix 秒)。 |
market_value_eur | null | 兼容占位,恒为 null;身价一律取 market_value。 |
字段覆盖率因球员而异:身价、年薪、评分来自上游深度档案,冷门联赛的部分球员这些字段为 null,属正常情况。
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/players/100001"
GET /managers/{manager_id} — 主教练档案与执教数据
按 manager_id 取主教练档案;未命中返回 {"found": false}(不是 404)。
| 字段 | 类型 | 说明 |
|---|---|---|
manager_id | int | 教练 ID。 |
name | string | 姓名。 |
team | string | 现任球队中文名;本地无该球队时为空串。 |
nationality country | string | 国籍(两列同源)。 |
current_team_id | int | null | 现任球队 ID。 |
tactical_profile | string | 战术倾向标签,取值 attacking / balanced / defensive。 |
preferred_formation | string | 惯用阵型,如 4-2-3-1。 |
matches_total wins draws losses | int | 执教总场次 / 胜 / 平 / 负。 |
win_pct | number | 胜率(百分数,60.3 即 60.3%)。 |
avg_goals_scored avg_goals_conceded | number | 场均进球 / 场均失球。 |
avg_possession | number | 场均控球率(百分数)。 |
clean_sheet_pct | number | 零封场次占比(百分数)。 |
btts_pct | number | 双方均有进球的场次占比(百分数)。 |
over_25_pct | number | 总进球大于 2.5 的场次占比(百分数)。 |
stats_updated_at | string | null | 上游统计快照时间(ISO 8601)。 |
tactics formations | null | 兼容占位,恒为 null;战术看 tactical_profile,阵型看 preferred_formation。 |
updated_at | number | 本行最后更新时间(Unix 秒)。 |
胜负平与场均数据按该教练的执教场次统计,随赛季推进更新;暂无执教记录时相关字段可能为 null。
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/managers/100001"
GET /coaches/{coach_id} — 教练详情(战绩 / 执教履历 / 近期比赛)
按 coach_id 取教练完整档案与按比赛统计的战绩;可传任一历史 ID,服务端会归一到主 ID,并在 coach_id / coach_ids / merged 里回显归一结果。未命中返回 {"found": false, ...}(不是 404,其余键仍在)。与第 16 节 /managers/{manager_id} 小节的关系:/managers 只给档案 + 上游赛季统计,本接口是超集,另给「按比赛算的战绩 / 执教履历 / 近期比赛 / ID 归一」;两边 profile 字段口径一致。
| 字段 | 类型 | 说明 |
|---|---|---|
found | bool | 是否查到此教练;为 false 时其余键仍然存在(空值),不是 404。 |
coach_id | int | 归一后的教练 ID:传别名进来也会换成主 ID。 |
coach_ids | int[] | 该教练的全部 ID(主 ID 在前,含所有别名)。 |
merged | int | 被合并的别名条数;0 表示没有别名。 |
days | int | 本次统计窗口天数,默认 365,钳制到 1~3650。 |
profile | object | 档案,7 键恒存在:name nationality country preferred_formation tactical_profile current_team_id current_team,与 /managers 同口径。 |
upstream_stats | object | 上游赛季统计,11 个数值键 + 快照时间:matches_total wins draws losses win_pct avg_goals_scored avg_goals_conceded avg_possession clean_sheet_pct btts_pct over_25_pct 与 stats_updated_at;冷门联赛 / 新教练可能全为 null,属正常情况不是故障。 |
record | object | 按比赛逐场算的战绩:matches wins draws losses goals_for goals_against points points_per_match(保留 2 位小数,0 场时为 null),并回显 days coach_ids merged。 |
teams | array | 执教履历,按最近执教日期倒序。每项:team_id team matches wins draws losses goals_for goals_against first_date last_date(日期为 YYYY-MM-DD)。 |
recent | array | 近期比赛,按 event_date 倒序,最多 limit 条(默认 20,钳制到 1~100)。每项:event_id event_date(UTC,ISO 8601)side(home / away)team opponent league home_score away_score goals_for goals_against result(win / draw / loss,未开赛或无比分时为空串 "")status(上游原文,如 finished / notstarted / postponed)。 |
aliases | array | ID 归一明细,含本人那一行。每项:coach_id name team。 |
四条口径:①record 与 upstream_stats 是两套数据,不能互相印证——前者由本库按「该场由谁执教 + 该场终场比分」逐场累加、窗口由 days 决定,后者是数据源给的赛季汇总,口径与时间窗都不同,数字不同属正常,不要当矛盾。②teams[].matches 之和恒等于 record.matches(同一口径、同一窗口),可用于对账。③只统计有终场比分的场次:未开赛 / 推迟 / 取消的场次不计入 record 与 teams,但仍会出现在 recent 里(此时 result 为空串,home_score / away_score / goals_for / goals_against 为 null)。④本接口只返回事实,不含任何评分、排名或加权结论;tactical_profile 是上游给的标签(attacking / balanced / defensive),不是本服务的评级。
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/coaches/4346?days=365&limit=20"
GET /teams/{team_id}/squad — 球队阵容(含球员档案)
按 team_id 取该队完整阵容;未收录阵容返回 {"found": false, "team_id": N, "count": 0, "players": []}(不是 404)。球员按球衣号排序,无号码的排在最后。
| 字段 | 类型 | 说明 |
|---|---|---|
shirt_number | int | 球衣号;上游未给时为 0。 |
player_id | int | 球员 ID,可直接用于 /players/{player_id}。 |
name short_name | string | 全名 / 简称。 |
name_zh short_name_zh | string | 中文名:有映射时返回中文,无映射时回落英文原名。 |
position specific_position | string | 位置组(G / D / M / F)/ 具体位置(如 ST)。 |
preferred_foot | string | 惯用脚(L / R)。 |
market_value | number | null | 身价,单位欧元。 |
wage_eur_annual contract_until | number / string | null | 年薪(欧元)/ 合同到期日。 |
rating | number | null | 能力评分。 |
nationality birthdate height weight | mixed | 国籍 / 出生日期 / 身高(厘米)/ 体重(公斤)。 |
potential injury_risk | string | null | 成长评价 / 伤病风险标签(上游原文枚举,未翻译)。 |
photo updated_at | string / number | 头像地址(可能为空串)/ 最后更新时间(Unix 秒)。 |
market_value_eur | null | 兼容占位,恒为 null;身价取 market_value。 |
与 /match_full 的关系:单场分析不必再调本接口 —— /match_full 的 lineups.home / lineups.away 已新增 players_detail,与 players 等长同序,逐人给出上述档案,并用 matched(是否匹配到)与 match_by(shirt+name / shirt+last / name / last / miss)标注可信度:必须球衣号与姓名双重佐证才判命中,无姓名证据即 matched:false(不会仅凭球衣号就把别人的档案挂上来)。players_detail[i].raw 与 players[i] 逐字相同,可直接用于反查;players 原始字符串数组保持不变,向后兼容。此外 lineups.home / lineups.away 还带 count(人数)、formation(阵型)、players_by_pos(按中文位置分组的原始阵容串,形如 {"门将": [...], "后卫": [...], "中场": [...], "前锋": [...]})与 players(原始字符串数组)
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/teams/5503/squad"
授权自检
粘贴你的 Token,点击按钮可查看套餐档位、今日剩余配额与到期时间。Token 只在当前页面内存中使用,不写入任何本地存储,也不会回显。
自检只调用 GET /api/profile,不返回任何赛事内容。
套餐与配额规则
展开查看总额度与配额口径
每次请求计 1 次额度。天数套餐有两层:每日上限 quota_daily 与每 30 天周期总额度 quota_total;次数包只有一层终身总次数 quota_lifetime,不限期限、不限每日。均可由 GET /api/profile 查到。
用聚合与批量接口可显著降低请求数:/history/{date} 一次取某日全部比赛,/odds_multi_batch 一次取多场赔率。
额度用尽返回 429;天数套餐的配额按自然日(Asia/Shanghai)重置,周期额度每 30 天滚动。
天数套餐(plan = pro)
每日 quota_daily 次、每 30 天 quota_total 次;到期时间以 expires_at 为准,续费顺延、Token 不变。
次数包(plan = pack)
不限期限、不限每日用量,只限总次数:从首次调用开始累计,用尽即止,不按月清零,Token 永久有效。
计费口径:每个带 Token 的请求计 1 次(含并发拉详情)。唯一不计次的是 GET /api/profile。想知道还剩多少次,可随时查它:
curl --compressed -H "X-API-Token: <你的Token>" \ "https://huhuan.hb.cn/api/profile" # → {"plan":"pack","quota_lifetime":10000,"quota_lifetime_left":8568,"quota_exhausted":false, ...}
剩余次数由服务端实时统计。若 usage_live 为 false,说明拿到的是最近一次落库值,最多滞后 usage_lag_max 秒(默认 15 秒)—— 做界面展示时按此提示用户即可,不必当成故障。
次数用尽后数据接口返回 429(总调用次数已用尽…),Token 不会失效;兑换新的次数包后立即恢复,剩余次数按叠加计算,Token 保持不变。
常见问题
返回 401,说 Token 无效
先确认请求头名字是 X-API-Token,值是完整 Token(不要带 Bearer 前缀,除非改用 Authorization 头)。也可以在上方「授权自检」里粘一次 Token 验证是否可用。
返回 200 但列表是空的
先看日期格式:/matches?date= 与 /day_fixtures?date= 现在 DD/MM/YYYY 与 YYYY-MM-DD 两种都接受(写错会 400,不再静默返回空集);/history/{date} 只接受 ISO,传斜杠日期会 404。详见 第 2 节。
返回 429,说超出限制
额度已用尽,或短时间内并发过高被临时限流。降低并发、改用聚合 / 批量接口,或查看 GET /api/profile 的剩余额度。具体规则见上方「套餐与配额规则」。
为什么有些端点返回 404
三类原因:event_id 不存在;该端点已下架(见 第 13 节);该端点对你当前套餐不开放。按响应体 detail 区分。