开发者工具化实战：王者荣耀全国战力查询 API 接入指南
·
适用场景
王者荣耀全国战力查询 API 为开发者提供了一套标准化的接口，可以获取以下两类核心数据：
- 英雄列表：返回 130+ 个英雄的中文名、ename（数字 ID）、称号、头像 URL 等元信息，可用于构建英雄选择器或数据展示 UI。
- 战力分布数据：针对指定英雄和区服（Android QQ / Android 微信 / iOS QQ / iOS 微信），查询其在全国各省、市、区的战力排名分布（约 90 条记录），支持返回完整列表、仅最低战力相近排名或仅最高战力相近排名。
典型应用包括：
- 开发“国服战力查询”小程序或公众号，用户输入英雄和区服即可查看所在省份的门槛战力。
- 爬取多个英雄的历史战力数据，用于分析版本强度变化或制作数据报告。
- 在游戏社群工具中集成战力对比功能，辅助玩家决策。
接口能力边界
- 请求方式：GET
- 基准地址：
https://v1.apizero.cn/api/wzry - 速率限制：5 QPS（每秒请求数），超出后可能返回 429 状态码或限流提示，具体以服务端实际行为为准。
- 数据新鲜度：响应中包含
syn_date字段（如"2026-05-06"），表示该数据的同步日期，并非实时数据，通常为每日或每周更新，请勿期望秒级实时。 - 查询范围：
action=query时返回约 90 条省/市/区级记录，覆盖主要地区和部分相近排名；完整榜单可能受限于官方数据源。
请求参数详解
Query 参数
| 参数名 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
action | 是 | string | 操作类型：heroes 获取英雄列表，query 获取战力查询 | query |
hero | 否 | string | 英雄中文名（如 赵云）；与 hero_id 二选一，action=query 时必传其一 | 赵云 |
hero_id | 否 | number | 英雄 ename（如赵云为 107）；与 hero 二选一，若同时提供则 hero_id 优先级更高 | 107 |
zone | 否 | string | 区服代码：aqq = Android QQ, awx = Android 微信, iqq = iOS QQ, iwx = iOS 微信；action=query 时必填 | aqq |
type | 否 | string | 返回类型：all 完整列表（默认），min 仅最低战力及相近排名，max 仅最高战力及相近排名 | min |
注意：当
action=heroes时，只需传入action参数，其余参数会被忽略。
Header 参数
| 参数名 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|
Authorization | 否 | string | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时每日有调用次数限制（具体以文档为准） | Bearer sk_live_xxxxxxxxxxxxxx |
鉴权方式也支持通过 X-API-Key 头传递，两种方式二选一。匿名调用可省略鉴权头，但每日配额有限，超出后可能返回 403 或 429。建议在生产环境使用 API Key 以避免中断。
curl 请求示例
获取英雄列表
curl -sS -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
"https://v1.apizero.cn/api/wzry?action=heroes"
查询战力（匿名调用）
curl -sS -X GET \
"https://v1.apizero.cn/api/wzry?action=query&hero=赵云&zone=aqq&type=min"
查询战力（带鉴权）
curl -sS -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
"https://v1.apizero.cn/api/wzry?action=query&hero_id=107&zone=iwx&type=max"
Python 代码接入示例
以下 Python 脚本演示如何先获取英雄列表，再查询某个英雄的最低战力分布。
import requests
BASE_URL = "https://v1.apizero.cn/api/wzry"
API_KEY = "sk_live_xxxxxxxxxxxxxx" # 可选
HEADERS = {}
if API_KEY:
HEADERS["Authorization"] = f"Bearer {API_KEY}"
# 1. 获取英雄列表
params = {"action": "heroes"}
resp = requests.get(BASE_URL, params=params, headers=HEADERS)
heroes_data = resp.json()
if heroes_data.get("code") == 0:
hero_list = heroes_data["data"]
# 打印前5个英雄
for hero in hero_list[:5]:
print(f"{hero['ename']} - {hero['cname']}（{hero['title']}）")
else:
print("获取英雄列表失败:", heroes_data.get("msg"))
exit(1)
# 2. 查询赵云（ename=107）在 Android QQ 区的最低战力
params = {
"action": "query",
"hero_id": 107,
"zone": "aqq",
"type": "min"
}
resp = requests.get(BASE_URL, params=params, headers=HEADERS)
query_result = resp.json()
if query_result.get("code") == 0:
data = query_result["data"]
print(f"英雄：{data['hero']['name']}")
print(f"区服：{data['zone']['system']} {data['zone']['platform']}")
print(f"数据类型：{data['type']}")
print(f"数据日期：{data['syn_date']}")
rank_data = data["rank_data"]
extreme = rank_data.get("extreme", {})
for level in ["province", "city", "district"]:
if level in extreme:
info = extreme[level]
print(f"{level}: {info['address']}，战力 {info['rank']}")
similar = rank_data.get("similar", {})
for level in ["province", "city", "district"]:
items = similar.get(level, [])
for item in items:
print(f"相近 {level}: {item['address']}，战力 {item['rank']}")
else:
print("查询失败:", query_result.get("msg"))
注意：实际返回的数据结构可能因 type 参数而异，务必根据响应中的 type_code 进行解析。
返回字段解读
以下是 action=query 且 type=min 时的 JSON 结构示例（已脱敏）：
{
"code": 0,
"msg": "成功",
"request_id": "abc123def456",
"data": {
"action": "query",
"hero": {
"avatar": "https://game.gtimg.cn/images/yxzj/img201606/heroimg/107/107.jpg",
"ename": "107",
"name": "赵云",
"title": "苍天翔龙"
},
"rank_data": {
"extreme": {
"province": {
"adcode": "530000",
"address": "云南",
"level": "province",
"rank": 4500
},
"city": {
"adcode": "460200",
"address": "海南/三亚市",
"level": "city",
"rank": 1800
},
"district": {
"adcode": "110105",
"address": "北京/朝阳区",
"level": "district",
"rank": 800
}
},
"similar": {
"province": [
{ "address": "云南", "rank": 4500 },
{ "address": "甘肃", "rank": 4520 }
],
"city": [],
"district": []
}
},
"syn_date": "2026-05-06",
"type": "最低战力",
"type_code": "min",
"zone": {
"code": "aqq",
"platform": "QQ",
"system": "Android"
}
}
}
关键字段说明
| 路径 | 类型 | 含义 |
|---|---|---|
code | int | 业务状态码，0 表示成功，非 0 表示异常 |
msg | string | 状态描述 |
request_id | string | 本次请求的唯一标识，可用来排查问题 |
data.hero | object | 英雄基本信息（name、ename、title、avatar） |
data.rank_data.extreme | object | 各级（province/city/district）的战力极值（当 type=min 时为最低战力，type=max 时为最高战力） |
data.rank_data.extreme.province.rank | number | 省级战力数值（国服最低/最高） |
data.rank_data.similar | object | 与极值战力相近的排名列表，keys 为 province/city/district，值为数组（可能为空） |
data.syn_date | string | 数据同步日期，格式 YYYY-MM-DD |
data.type_code | string | 返回类型：all、min、max，与请求参数一致 |
data.zone | object | 区服信息，包含 code、platform、system |
当 type=all 时，rank_data 的结构会不同，不再有 extreme 和 similar，而是直接返回一个约 90 项的数组（按 level 混合排列）。建议根据 type_code 动态解析。
常见错误处理
| HTTP 状态码 | 可能原因 | 处理建议 |
|---|---|---|
| 200（code≠0） | 参数错误、鉴权失败、限流 | 查看 msg 字段确定具体错误，如 "缺少必要参数"、"无权限访问"、"请求过于频繁" |
| 400 | 请求格式错误（如无效参数值） | 检查是否传入了非法字符或类型不匹配 |
| 403 | 鉴权失败或匿名用户超出每日限额 | 检查 API Key 是否正确，或等待配额重置 |
| 429 | 请求频率超限（QPS > 5） | 实现指数退避重试，或将请求分散到不同时间片 |
| 5xx | 服务端内部错误 | 可重试，若持续失败需联系 API 提供方 |
参数校验注意事项
hero和hero_id只能二选一，同时传时以hero_id为准。zone必须为aqq/awx/iqq/iwx之一，否则返回错误。- 英雄名称必须与官方完全一致（如“赵云”不能写作“赵子龙”），建议先调用
action=heroes获取合法名称列表。
工程化注意事项
- 缓存策略：英雄列表变化频率极低（基本只在版本更新时增加新英雄），建议本地缓存至少 24 小时。战力数据建议缓存 1 小时以上，避免频繁请求被限流。
- 限速与重试：QPS 限制为 5，并发请求时需加锁或使用令牌桶控制。推荐使用
retry库在遇到 429 或 5xx 时自动重试（最多 3 次，间隔 1s、2s、4s）。 - 请求 ID 记录：每次请求的
request_id应记录到日志，方便排查问题。 - 参数安全：避免直接将用户输入拼接到 URL 中，应先进行校验或使用 URL 编码。
- 数据分页：
action=query目前不提供分页参数，若需获取全部记录（如type=all时返回约 90 条），直接使用即可。 - 跨平台兼容：不同区服的战力数据独立，查询时需明确用户选择的区服。
实战示例：构建一个简易战力查询 CLI
以下是一个使用 Python 和 argparse 的命令行工具，接受英雄名称、区服、类型参数，输出简要结果：
import argparse
import requests
import json
API_URL = "https://v1.apizero.cn/api/wzry"
def main():
parser = argparse.ArgumentParser(description="王者荣耀战力查询 CLI")
parser.add_argument("--hero", required=True, help="英雄中文名")
parser.add_argument("--zone", required=True, choices=["aqq","awx","iqq","iwx"], help="区服代码")
parser.add_argument("--type", default="min", choices=["all","min","max"], help="返回类型")
parser.add_argument("--key", default="", help="API Key (可选)")
args = parser.parse_args()
headers = {}
if args.key:
headers["Authorization"] = f"Bearer {args.key}"
params = {
"action": "query",
"hero": args.hero,
"zone": args.zone,
"type": args.type
}
resp = requests.get(API_URL, params=params, headers=headers)
if resp.status_code != 200:
print(f"HTTP {resp.status_code}: {resp.text}")
return
data = resp.json()
if data.get("code") != 0:
print(f"业务错误: {data.get('msg')}")
return
info = data["data"]
print(f"\n{info['hero']['name']} - {info['zone']['system']} {info['zone']['platform']}")
print(f"数据日期: {info['syn_date']}")
rank_data = info["rank_data"]
if args.type != "all":
extreme = rank_data.get("extreme", {})
for level in ["province","city","district"]:
if level in extreme:
item = extreme[level]
print(f"{level}: {item['address']} -> 战力 {item['rank']}")
similar = rank_data.get("similar", {})
for level in ["province","city","district"]:
items = similar.get(level, [])
if items:
print(f"相近 {level}: {', '.join([f'{i["address"]}({i["rank"]})' for i in items])}")
else:
# all 类型直接输出列表数量
items = rank_data.get("list", [])
print(f"共 {len(items)} 条记录")
for item in items[:5]: # 显示前5条
print(f" {item['address']} - {item['rank']}")
if __name__ == "__main__":
main()
使用方法：
python wzry_cli.py --hero 赵云 --zone aqq --type min
参考文档
- 接口文档页
- 原始 Markdown 文档
- 官方英雄列表源：https://pvp.qq.com/web201605/js/herolist.json（仅做参考，本接口已聚合）
更多推荐
0
0- 0
已为社区贡献3条内容
所有评论(0)