从第一条请求开始接入 HaiYang 王者荣耀战力 API
如果你想在自己的网站或机器人里展示某个英雄的最低上榜门槛,可以从 HaiYang 的两个公开接口开始:先找英雄,再查战力。
本文按照接口文档介绍这条接入流程。参数和成功返回已经实际核对,示例使用孙尚香的英雄 ID 111。
两个接口,完成一次查询
接口域名是 https://wz.hay7.cn,请求方式均为 GET,返回格式为 JSON。
| 接口 | 用途 |
|---|---|
/api/v1/heroes | 获取英雄 ID、名称、称号与内部名 |
/api/v1/power | 按英雄、平台查询省市区最低门槛 |
当前文档中的公开请求示例没有要求传入密钥。接入规则如有调整,以最新文档为准。
第一步:获取英雄列表
英雄列表接口无需业务参数:
curl "https://wz.hay7.cn/api/v1/heroes"成功响应中,data 是英雄数组。每项包括:
hero_id:英雄 ID,适合作为后续查询参数。hero_name:英雄名称。hero_title:英雄称号。id_name:内部名称。
将这份列表缓存起来,用它制作选择器或校验用户输入,就不用每次查战力都重新拉取英雄列表。
第二步:按英雄和平台查询
下面查询孙尚香、安卓 QQ、省市区各取最低的 1 个地区:
curl "https://wz.hay7.cn/api/v1/power?hero=111&platform=aqq&top=1"如果只需要区县榜,加上 level=county:
curl "https://wz.hay7.cn/api/v1/power?hero=111&platform=aqq&top=1&level=county"两种查询的区别在于返回的地区层级。第二条只请求区县记录,不需要把省、市的数据也拉回来。
参数怎么选
| 参数 | 必填 | 含义与取值 |
|---|---|---|
hero | 是 | 英雄 ID 或准确名称,例如 111、孙尚香 |
platform | 否 | aqq 安卓 QQ、iqq 苹果 QQ、awx 安卓微信、iwx 苹果微信;不传返回四个平台 |
top | 否 | 每个层级返回的地区数,取值 1~10,默认 5 |
level | 否 | province 省、city 市、county 区县;不传返回三个层级 |
这里有两个容易忽略的地方:
top 是每个层级的数量。 top=3 且不传 level,请求的是省、市、区县各自最多 3 条记录,不是总共 3 条。
platform 用于选择榜单。 用户是什么平台,就传对应的值。需要跨平台比较时再省略它。
参数含中文名称时,用 URL 编码工具构造查询字符串。后面的 JavaScript 示例使用 URLSearchParams,不用手动拼接或转义。
读懂返回值,比发出请求更重要
先判断顶层业务状态:code === 0 才表示业务成功。HTTP 200 只能说明收到响应,还要结合 code 和 msg 处理查询结果。
以安卓 QQ 为例,平台数据位于:
data.platforms.aqq下面是省略其他字段后的结构示意。门槛与日期是演示值,不代表实时结果:
{ "code": 0, "msg": "ok", "data": { "heroId": 111, "heroName": "孙尚香", "platforms": { "aqq": { "name": "安卓QQ", "date": "2026-09-18", "updatetime": "2026-09-18 05:10:05", "stale": false, "county": [ { "rank": 1, "adcode": 230719, "region": "友好区", "power": 1793 } ] } } }}地区记录中,rank 是按门槛从低到高的顺序,rank: 1 对应最低门槛;adcode 是地区代码,region 是地区名称,power 是门槛数值。
展示结果时,也建议带上平台数据中的 date 和 updatetime。stale: true 表示数据较旧,应该保留这个提示,而不是只显示一个看起来很新的数值。
响应还可能包含全国榜 national,没有记录时为 null。它与省、市、区县的地区门槛列表不同,接入时需要分别处理。完整结构可参考文档中的返回示例。
一个可以运行的 Node.js 示例
下面使用 Node.js 22 或更新版本,直接调用内置 fetch,无需额外依赖。把代码保存为 query-power.mjs,执行 node query-power.mjs。
const url = new URL("https://wz.hay7.cn/api/v1/power");url.search = new URLSearchParams({ hero: "111", platform: "aqq", top: "3", level: "county",}).toString();
try { const response = await fetch(url, { signal: AbortSignal.timeout(10_000), });
if (response.status === 429) { const retryAfter = response.headers.get("Retry-After"); throw new Error( retryAfter ? `请求受到限流,请按 Retry-After 提示稍后重试:${retryAfter}` : "请求受到限流,请等待后重试", ); }
if (!response.ok) { throw new Error(`HTTP 请求失败:${response.status}`); }
const result = await response.json(); if (result.code !== 0) { throw new Error(result.msg || "查询未成功"); }
const platform = result.data?.platforms?.aqq; if (!platform) { throw new Error("响应中没有安卓 QQ 的平台记录"); }
console.log(`${result.data.heroName} · ${platform.name}`); console.log(`数据日期:${platform.date ?? "未提供"}`); console.log(`更新时间:${platform.updatetime ?? "未提供"}`); if (platform.stale) console.warn("这份数据较旧,请留意更新时间。");
const rows = Array.isArray(platform.county) ? platform.county : []; if (rows.length === 0) { console.log("暂无区县记录,不代表门槛为 0。"); } else { console.table( rows.map((row) => ({ 排序: row.rank, 地区: row.region, 上榜门槛: row.power, })), ); }} catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1;}这段代码发起一次查询,检查 HTTP 与业务状态,再展示地区列表。遇到超时、限流或无记录,会给出对应信息。
正式接入时,做好这几件事
- 优先从自己的服务端调用。 将请求校验、缓存和异常处理放在一起,不必让每个访问者重复请求上游。
- 对相同查询复用结果。 英雄列表适当缓存;相同英雄、平台、层级和数量的战力查询也可以短时间复用。
- 收到 429 时等待。 按
Retry-After提示安排重试,不要立即循环请求。文档没有公布统一的每秒请求配额,不要自行假设。 - 把更新时间一起交给用户。 查询记录和游戏当前值可能存在时间差,旧数据和无记录都要明确表达。
遇到问题怎么反馈
可以提供这几项信息:接口路径、请求参数、HTTP 状态码、业务 code 与 msg、出现问题的时间。如果是数据问题,再附上英雄、平台和数据日期。
通过联系与支持反馈即可。如果只是想先看看查询效果,也可以直接使用网页版查询站,或阅读查询教程。
本文依据 HaiYang 的产品介绍与公开接口文档整理,核对日期为 2026 年 9 月 18 日。英雄列表、单平台查询和区县筛选请求均已验证成功;代码中的异常处理用于接入防护,不代表服务曾返回这些错误。
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!
HaiYang助手
