呼唤数据分析

接口文档

足球赛事数据结构化接口的字段说明与调用方式,面向已获得授权卡密的用户。
基础地址 https://huhuan.hb.cn

三步上手

  1. 拿到激活卡密

    会收到一串卡密,形如 XXXX-XXXX-XXXX。激活在网页上进行,不是 API 调用。

  2. 到激活页换取 Token

    打开 卡密激活页,填入卡密提交,页面会显示一串 Token,请自行保存。

  3. 把 Token 填进客户端

    客户端里直接粘贴;自己写程序时放进请求头 X-API-Token,见 第 1 节。

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 调用;路径单元格在窄屏自动折行。

对外数据接口清单,共 44 条
方法路径说明
GET/api/leagues联赛数字 ID → 中文短名映射(单一真源)
GET/api/match/{match_id}加工层单场详情,含时间序列曲线
GET/api/matches加工层赛事列表,date 两种格式均可
GET/api/ping无参探活,无需鉴权,返回固定 JSON
GET/api/profile查询自身套餐、配额与到期时间
GET/api/standings联赛积分榜,需带 league 或 league_id
GET/api/standings_xg积分榜并附带 xG 口径字段
GET/api/today今日赛事列表(含 league_id)
GET/archive/matches历史赛果库(永久归档 2020→今)
GET/bookmakers赔率来源(公司)列表
GET/broadcasts/{event_id}某场比赛的转播信息
GET/coaches/{coach_id}教练详情(战绩 / 执教履历 / 近期比赛)
GET/day_fixtures按日赛程列表,date 支持 dd/mm/yyyy 与 YYYY-MM-DD
GET/events/{event_id}该场逐分钟事件(进球 / 红黄牌 / 换人)
GET/expected_xg/{event_id}首选口径 xG 预期(与 /matches 同源 ID)
GET/h2h/{event_id}该场历史交锋记录
GET/history/{date}某日全部比赛聚合,inline 三档可选
GET/injuries/all全部伤停信息汇总
GET/injuries/{event_id}该场伤停列表
GET/leagues/{league_id}按联赛 ID 取联赛详情
GET/lineups/{event_id}该场阵容(阵型与首发 / 替补)
GET/managers/{manager_id}按教练 ID 取教练信息
GET/match/{event_id}单场基础信息行(联赛 / 队名 / 比分)
GET/match_clv/{event_id}收盘线价值(CLV)三路数值
GET/match_full/{event_id}单场完整数据(13 张子表装配)
GET/match_odds_hist/{event_id}该场赔率历史记录
GET/match_shotmap/{event_id}单场射门落点与平均站位
GET/match_stats/{event_id}该场技术统计(含半场 xG)
GET/matches赛事列表(快照层,支持 date 与分页)
GET/odds/{event_id}单场赔率(含封盘标记)
GET/odds_curve/{event_id}各公司赔率时间序列
GET/odds_multi/{event_id}多市场赔率
GET/odds_multi_batch批量取多场多市场赔率,省配额
GET/players/{player_id}按球员 ID 取球员信息
GET/referees/{referee_id}按裁判 ID 取裁判信息
GET/search按队名子串检索比赛,最多 50 条
GET/seasons赛季列表
GET/snapshot/history历史每日快照(筛选 + 分页)
GET/team_xg_form/{team}球队近期 xG 形态,n 默认 10
GET/teams/name/{name}按球队名取球队信息
GET/teams/{team_id}按 team_id 取球队信息
GET/teams/{team_id}/fixtures球队赛程,最多 30 行
GET/venues球场 / 场馆列表
GET/venues/{venue_id}按场馆 ID 取场馆详情

另有为客户端优化的赛事专项接口,如需了解请联系运营方。

三步上手 接口总览 鉴权 卡密激活 日期与时区 /history 聚合 /match_full 详情 /matches 列表 联赛 ID 与中文名 xG 预期 赔率与 CLV 技术统计 历史数据端点 其它端点一览 错误码 已下架接口 字段口径变更说明 补充接口 授权自检 常见问题

1. 鉴权

所有数据接口需携带有效 Token,二选一:

方式请求头示例
建议X-API-TokenX-API-Token: <你的Token>
兼容AuthorizationAuthorization: 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)

响应中的日期字段(勿混淆)

字段格式说明
行内 dateDD/MM/YYYY如 01/09/2026(上海日期);/history、/matches、/snapshot/history、/archive/matches 的行均如此
顶层 data.dateYYYY-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。字段差异如下:

字段nonesummary(默认)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 调用取得。

新增响应字段

字段位置说明
totaldata.total该日真实总行数(本端点不分页,故通常与 count 相等)。
filtered_emptydata.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 天窗口、同友谊赛排除规则),所以"详情页里的近期状态"与"直接调该接口"不会出现两套数字。

字段类型说明
limitint每侧取几场,当前 8。
daysint时间窗(天),当前 365,只统计窗内已完赛。
include_friendlybool是否含友谊赛,当前 false(默认排除)。被排除的场次数见各队的 excluded_friendly。
home / awayobject主 / 客队的战绩对象,结构见下一张表。

home 与 away 的对象结构:

字段类型说明
foundbool是否取到该队战绩。
team_id / team_name / team_knownint / string / bool球队 ID、中文名、是否在球队表内。
countint实际返回场次(≤ limit)。
excluded_friendlyint因 include_friendly:false 被排除的友谊赛场次。
reasonstring取不到时的原因;正常为空串。
summaryobjectplayed / wins / draws / losses / goals_for / goals_against / win_pct(百分数,如 37.5)。
matchesarray逐场明细,按时间倒序,见下。

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 需鉴权

GET /matches?date=DD/MM/YYYY&limit=&offset=&q=

兼容接口:date 接受 DD/MM/YYYY(如 01/09/2026)与 ISO(如 2026-09-01)两种写法,两者等价。返回列表 + 赔率可用性元数据。格式非法或日期不存在时返回 400,不再静默给出 count=0,详见第 2 节。

每行新增联赛数字 ID 字段 league_id(整数)与中文名 league_zh,见 第 6 节。

每行开球时间字段 time(上游未提供时为 null)与布尔字段 time_known(false = 时间未知),见 第 14 节。

6. 联赛 ID 与中文名 GET 需鉴权

GET /api/leagues

返回全部联赛的 数字 ID → 中文名 映射,用于把比赛行里的 league_id 还原为可读联赛名。

响应结构

{
  "leagues": {
    "1234": "西甲",
    "1235": "意甲",
    ...
  }
}

键为联赛数字 ID(字符串形式),值为对应中文短名。该 ID 与比赛响应中的 league_id 同源,可直接 join。该映射现以 leagues 表为单一真源,共 91 个键。

行内新增 league_id 字段

端点新增字段说明
/matchesleague_id(整数)、league_zh(中文名)可直接用 league_id 关联 /api/leagues。
/api/todayleague_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_open0 表示仅 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_closedbool赔率是否已封盘;比赛已结束时为 true。
odds_closed_reasonstring | 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} 4042026-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_idint与 leagues.league_id 同源,可用于跨接口对齐。
league_zhstring联赛中文短名(如「西甲」「英超」)。

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 原始行、未做归一):

字段类型说明
timestring | null开球时间;上游未提供时为 null。
time_knownboolfalse = 时间未知;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 响应中移除,请勿再依赖该字段。

字段类型说明
countint语义为本页返回条数(已剔除空壳行之后)。

空壳行判据(保守):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()。

字段类型说明
countint返回场次条数,等于 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 口径)。可以随意轮询做余额提醒,不必担心把额度查没了。

字段类型说明
planstring套餐档位;pack 表示「次数包」。
statusstring账号状态。
created_atnumber创建时间(Unix 秒)。
expires_atnumber | null到期时间(Unix 秒);null 表示永久。
expires_strstring到期时间的可读文本;永久时为「永久」。
quota_dailynumber每日调用上限;0 表示不限。
quota_totalnumber周期(30 天)额度上限;0 表示不限。
quota_lifetimenumber次数包专用:终身总次数;0 表示当前账号不是次数包。
quota_lifetime_leftnumber | null剩余次数;非次数包为 null(注意与「剩余 0 次」区分)。
quota_lifetime_usednumber | null已用次数;非次数包为 null。
quota_lifetime_pctnumber | null已用百分比(0–100)。
quota_exhaustedbool次数包是否已用尽(此时数据接口返回 429)。
quota_lowbool次数是否告急(剩余 ≤ 10% 或 ≤ 200 次)。
usage_livebool用量数字是否为服务端实时值。false 表示取的是最近一次落库值,最多滞后 usage_lag_max 秒(默认 15)。
usage_lag_maxnumber落库周期上限(秒)。
server_timenumber服务端当前时间(Unix 秒)。
used_todaynumber今日已用次数;剩余 = quota_daily - used_today(quota_daily=0 时不适用)。
total_usednumber累计已用次数(终身)。
max_concurrentnumber并发上限。
is_expiredbool是否已过期。
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 ptsint排名 / 球队 ID / 场次 / 胜 / 平 / 负 / 进球 / 失球 / 净胜球 / 积分。
xgf xga xgdfloatxG 口径的进球、失球与净差值。
xg_gamesint参与 xG 计算的场次数。
formstring近期战绩串。
livebool是否为进行中的实时口径。

数值解析失败的字段返回 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_idint球员 ID。
name short_namestring全名 / 简称。
name_zh short_name_zhstring中文名。有映射时返回中文,无映射时回落英文原名(不是空串);前端展示优先用它。
nationalitystring国籍。
birthdatestring出生日期 YYYY-MM-DD。
height weightnumber | null身高(厘米)/ 体重(公斤)。
position specific_positionstring位置组(如 F)/ 具体位置(如 ST)。
preferred_footstring惯用脚(L / R)。
market_valuenumber | null身价,单位欧元。如 240000000.0 即 2.4 亿欧。
wage_eur_annualnumber | null年薪,单位欧元。
contract_untilstring | null合同到期日 YYYY-MM-DD。
ratingnumber | null能力评分。
potential injury_riskstring | null成长评价 / 伤病风险标签(上游原文枚举,未翻译)。
current_team_id national_team_idint | null所属俱乐部 / 国家队 ID,可用第 11 节 /teams/{team_id} 展开队名。
photostring头像地址,可能为空串。
updated_atnumber本行最后更新时间(Unix 秒)。
market_value_eurnull兼容占位,恒为 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_idint教练 ID。
namestring姓名。
teamstring现任球队中文名;本地无该球队时为空串。
nationality countrystring国籍(两列同源)。
current_team_idint | null现任球队 ID。
tactical_profilestring战术倾向标签,取值 attacking / balanced / defensive。
preferred_formationstring惯用阵型,如 4-2-3-1。
matches_total wins draws lossesint执教总场次 / 胜 / 平 / 负。
win_pctnumber胜率(百分数,60.3 即 60.3%)。
avg_goals_scored avg_goals_concedednumber场均进球 / 场均失球。
avg_possessionnumber场均控球率(百分数)。
clean_sheet_pctnumber零封场次占比(百分数)。
btts_pctnumber双方均有进球的场次占比(百分数)。
over_25_pctnumber总进球大于 2.5 的场次占比(百分数)。
stats_updated_atstring | null上游统计快照时间(ISO 8601)。
tactics formationsnull兼容占位,恒为 null;战术看 tactical_profile,阵型看 preferred_formation。
updated_atnumber本行最后更新时间(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 字段口径一致。

字段类型说明
foundbool是否查到此教练;为 false 时其余键仍然存在(空值),不是 404。
coach_idint归一后的教练 ID:传别名进来也会换成主 ID。
coach_idsint[]该教练的全部 ID(主 ID 在前,含所有别名)。
mergedint被合并的别名条数;0 表示没有别名。
daysint本次统计窗口天数,默认 365,钳制到 1~3650。
profileobject档案,7 键恒存在:name nationality country preferred_formation tactical_profile current_team_id current_team,与 /managers 同口径。
upstream_statsobject上游赛季统计,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,属正常情况不是故障。
recordobject按比赛逐场算的战绩:matches wins draws losses goals_for goals_against points points_per_match(保留 2 位小数,0 场时为 null),并回显 days coach_ids merged。
teamsarray执教履历,按最近执教日期倒序。每项:team_id team matches wins draws losses goals_for goals_against first_date last_date(日期为 YYYY-MM-DD)。
recentarray近期比赛,按 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)。
aliasesarrayID 归一明细,含本人那一行。每项: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_numberint球衣号;上游未给时为 0。
player_idint球员 ID,可直接用于 /players/{player_id}。
name short_namestring全名 / 简称。
name_zh short_name_zhstring中文名:有映射时返回中文,无映射时回落英文原名。
position specific_positionstring位置组(G / D / M / F)/ 具体位置(如 ST)。
preferred_footstring惯用脚(L / R)。
market_valuenumber | null身价,单位欧元。
wage_eur_annual contract_untilnumber / string | null年薪(欧元)/ 合同到期日。
ratingnumber | null能力评分。
nationality birthdate height weightmixed国籍 / 出生日期 / 身高(厘米)/ 体重(公斤)。
potential injury_riskstring | null成长评价 / 伤病风险标签(上游原文枚举,未翻译)。
photo updated_atstring / number头像地址(可能为空串)/ 最后更新时间(Unix 秒)。
market_value_eurnull兼容占位,恒为 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 区分。