从第一条请求开始接入 HaiYang 王者荣耀战力 API

1598 字
8 分钟
从第一条请求开始接入 HaiYang 王者荣耀战力 API

如果你想在自己的网站或机器人里展示某个英雄的最低上榜门槛,可以从 HaiYang 的两个公开接口开始:先找英雄,再查战力。

本文按照接口文档介绍这条接入流程。参数和成功返回已经实际核对,示例使用孙尚香的英雄 ID 111。

两个接口,完成一次查询#

接口域名是 https://wz.hay7.cn,请求方式均为 GET,返回格式为 JSON。

接口用途
/api/v1/heroes获取英雄 ID、名称、称号与内部名
/api/v1/power按英雄、平台查询省市区最低门槛

当前文档中的公开请求示例没有要求传入密钥。接入规则如有调整,以最新文档为准。

第一步:获取英雄列表#

英雄列表接口无需业务参数:

Terminal window
curl "https://wz.hay7.cn/api/v1/heroes"

成功响应中,data 是英雄数组。每项包括:

  • hero_id:英雄 ID,适合作为后续查询参数。
  • hero_name:英雄名称。
  • hero_title:英雄称号。
  • id_name:内部名称。

将这份列表缓存起来,用它制作选择器或校验用户输入,就不用每次查战力都重新拉取英雄列表。

第二步:按英雄和平台查询#

下面查询孙尚香、安卓 QQ、省市区各取最低的 1 个地区:

Terminal window
curl "https://wz.hay7.cn/api/v1/power?hero=111&platform=aqq&top=1"

如果只需要区县榜,加上 level=county:

Terminal window
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 与业务状态,再展示地区列表。遇到超时、限流或无记录,会给出对应信息。

正式接入时,做好这几件事#

  1. 优先从自己的服务端调用。 将请求校验、缓存和异常处理放在一起,不必让每个访问者重复请求上游。
  2. 对相同查询复用结果。 英雄列表适当缓存;相同英雄、平台、层级和数量的战力查询也可以短时间复用。
  3. 收到 429 时等待。 按 Retry-After 提示安排重试,不要立即循环请求。文档没有公布统一的每秒请求配额,不要自行假设。
  4. 把更新时间一起交给用户。 查询记录和游戏当前值可能存在时间差,旧数据和无记录都要明确表达。

这些是调用方的实现建议。数据更新计划和接口规则,以调用说明及数据说明为准。

遇到问题怎么反馈#

可以提供这几项信息:接口路径、请求参数、HTTP 状态码、业务 code 与 msg、出现问题的时间。如果是数据问题,再附上英雄、平台和数据日期。

通过联系与支持反馈即可。如果只是想先看看查询效果,也可以直接使用网页版查询站,或阅读查询教程。

本文依据 HaiYang 的产品介绍与公开接口文档整理,核对日期为 2026 年 9 月 18 日。英雄列表、单平台查询和区县筛选请求均已验证成功;代码中的异常处理用于接入防护,不代表服务曾返回这些错误。

文章分享

如果这篇文章对你有帮助,欢迎分享给更多人!

从第一条请求开始接入 HaiYang 王者荣耀战力 API
https://www.hay7.cn/posts/honor-power-api/
作者
HaiYang助手
发布于
2026-09-18
许可协议
CC BY-NC-SA 4.0
Profile Image of the Author
HaiYang助手
用工具解决问题,用效率定义生活
公告
HaiYang助手一站式在线工具平台,精选工具,即开即用!
文章目录