王者荣耀全国战力查询API参数全解与工程化接入指南
适用场景与典型用例
王者荣耀全国战力查询API面向以下场景：
- 游戏数据工具：开发小程序或网站展示英雄省/市/区战力排名。
- 内容创作辅助：快速获取英雄战力分布，用于图文或视频数据支撑。
- 个人学习与测试：熟悉HTTP请求、JSON解析、限流控制等API工程实践。
- 电竞分析：按区服（Android/iOS + QQ/微信）分析特定英雄的竞争强度。
该API无需准备即可匿名调用（每日50次），适合个人和小型项目。
接口能力边界
核心功能
- 英雄列表：
action=heroes返回130+英雄的中文名、ename（数字ID）、称号和头像URL。数据源为腾讯官方https://pvp.qq.com/web201605/js/herolist.json，实时性高。 - 战力查询：
action=query根据英雄和区服，返回约90条省/市/区战力记录，包含：extreme：各省/市/区的最低或最高战力及排名（取决于type参数）。similar：与查询结果排名相近的其他地区（排名差≤100）。
约束说明
- QPS：5次/秒，超过会返回429错误。
- 请求方法：仅支持GET。
- 数据更新：根据字段
syn_date判断数据日期，通常为当日或前一日。
请求参数详解与鉴权
Query参数（必填与选填）
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
action | 是 | string | 操作类型：heroes（英雄列表）或query（战力查询） | query |
hero | 条件必填 | string | 英雄中文名，如“赵云”；action=query时与hero_id二选一 | 赵云 |
hero_id | 条件必填 | number | 英雄ename（数字ID，如赵云=107）；action=query时二选一，优先级高于hero | 107 |
zone | 条件必填 | string | 区服代码：aqq=Android QQ,awx=Android微信,iqq=iOS QQ,iwx=iOS微信 | aqq |
type | 否 | string | 返回类型：all（完整列表，默认）、min（最低战力）、max（最高战力） | min |
参数选择建议：
- 当英雄名称包含特殊字符或不确定时，优先使用
hero_id（ename），避免编码问题。 type=min可快速获取各等级的入门战力门槛，type=max查看天花板，all获取完整分布。
Header参数（鉴权）
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
Authorization | 否 | string | API Key鉴权，格式Bearer sk_live_xxx；匿名调用可省略（每日50次调用次数限制） | Bearer sk_live_xxxxxxxxxxxx |
无需鉴权即可调用，但建议生产环境使用密钥以避免额度不足。
可运行的请求示例
1. 获取英雄列表
curl -sS -X GET https://v1.apizero.cn/api/wzry?action=heroes | jq .返回示例片段：
{ "code": 0, "data": [ { "ename": 105, "cname": "赵云", "title": "苍天翔龙", "avatar": "https://game.gtimg.cn/images/yxzj/img201606/heroimg/105/105.jpg" }, ... ], "msg": "成功", "request_id": "xxx" }2. 查询英雄战力（带鉴权）
curl -sS -X GET \ -H "Authorization: Bearer sk_live_your_key_here" \ "https://v1.apizero.cn/api/wzry?action=query&hero_id=107&zone=aqq&type=min" | jq .参数说明：
hero_id=107对应赵云，zone=aqq为Android QQ区，type=min返回最低战力数据。
3. 使用Python接入（带错误处理）
import requests import json API_URL = "https://v1.apizero.cn/api/wzry" HEADERS = {} # 若需鉴权：{"Authorization": "Bearer sk_live_xxx"} def get_hero_list(): params = {"action": "heroes"} resp = requests.get(API_URL, params=params, headers=HEADERS) resp.raise_for_status() data = resp.json() if data.get("code") == 0: return data["data"] else: raise Exception(f"API error: {data.get('msg')}") def query_power(hero_name=None, hero_id=None, zone="aqq", query_type="min"): params = {"action": "query", "zone": zone, "type": query_type} if hero_id: params["hero_id"] = hero_id elif hero_name: params["hero"] = hero_name else: raise ValueError("hero_name or hero_id required") resp = requests.get(API_URL, params=params, headers=HEADERS) resp.raise_for_status() return resp.json() # 示例：查询赵云Android QQ区最低战力 result = query_power(hero_id=107) print(json.dumps(result, indent=2, ensure_ascii=False))4. 使用JavaScript (Fetch) 快速接入
const API = 'https://v1.apizero.cn/api/wzry'; const headers = {}; // 或 { 'Authorization': 'Bearer sk_live_xxx' } async function queryHeroPower(heroId, zone = 'aqq', type = 'min') { const params = new URLSearchParams({ action: 'query', hero_id: heroId, zone, type }); const response = await fetch(`${API}?${params}`, { headers }); if (!response.ok) throw new Error(`HTTP ${response.status}`); return response.json(); } // 调用 queryHeroPower(107).then(data => console.log(data));返回值结构与字段解读
以action=query&hero_id=107&zone=aqq&type=min的响应为例（节选）：
{ "code": 0, "data": { "action": "query", "hero": { "avatar": "https://game.gtimg.cn/images/yxzj/img201606/heroimg/107/107.jpg", "ename": "107", "name": "赵云", "title": "苍天翔龙" }, "rank_data": { "extreme": { "city": { "adcode": "...", "address": "海南/三亚市", "level": "city", "rank": 1800 }, "district": { "adcode": "...", "address": "北京/朝阳区", "level": "district", "rank": 800 }, "province": { "adcode": "...", "address": "云南", "level": "province", "rank": 4500 } }, "similar": { "city": [], "district": [], "province": [ {"address": "云南", "rank": 4500}, {"address": "甘肃", "rank": 4520} ] } }, "syn_date": "2026-05-06", "type": "最低战力", "type_code": "min", "zone": { "code": "aqq", "platform": "QQ", "system": "Android" } }, "msg": "成功", "request_id": "abc123def456" }核心字段解析：
| 字段路径 | 类型 | 说明 |
|---|---|---|
code | number | 0表示成功，非0见错误码 |
data.hero | object | 英雄基本信息：name（中文名）、ename（数字ID，字符串）、title（称号）、avatar（头像URL） |
data.rank_data.extreme | object | 各级别的最低/最高战力详情，包含province、city、district三个子对象 |
extreme.*.address | string | 地区完整名称，格式如“云南”或“北京/朝阳区” |
extreme.*.rank | number | 该级别的战力数值（注意：type=min时是最低战力，type=max时是最高战力） |
data.rank_data.similar | object | 与查询结果相近的其他地区（仅当type=min或max时返回），同省/市/区排名相差≤100的记录 |
similar.province | array | 省一级相近排名列表，每个元素含address和rank |
data.syn_date | string | 数据同步日期（格式 yyyy-MM-dd） |
data.type | string | 中文类型说明（“最低战力”/“最高战力”/“完整列表”） |
data.zone | object | 区服信息：code（内部代码）、platform（QQ/微信）、system（Android/iOS） |
注意：type=all时，rank_data结构不同，会返回一个完整的数组full_data，包含约90条省/市/区战力记录（按level混合排列）。此时extreme和similar字段不存在。
常见错误与排查方法
| 错误表现 | 可能原因 | 解决方案 |
|---|---|---|
| HTTP 400 | 缺少必填参数或参数格式错误 | 检查action、zone、hero/hero_id是否提供；zone仅允许aqq/awx/iqq/iwx |
| HTTP 401 | Authorization格式错误或Key无效 | 确认Header名称为Authorization，值以Bearer开头 |
| HTTP 429 | 请求频率超过QPS限制（5次/秒） | 加入本地限流，使用setTimeout或time.sleep控制间隔≥200ms |
| code=1001 | 英雄名称不存在或hero_id无效 | 先调用action=heroes获取合法列表，确认名称或ID正确 |
| code=1002 | 区服代码错误 | 只使用aqq/awx/iqq/iwx四种 |
| code=500 | 服务器内部错误或数据源异常 | 重试一次，若持续失败可检查syn_date是否正常，或联系支持 |
返回数据中rank_data为空 | 该英雄在该区服可能暂无排名数据（新英雄或冷门区） | 尝试更换type=all获取全部数据，或更换区服 |
工程化注意事项
1. 本地缓存策略
- 英雄列表变化频率低（仅当新英雄上线时更新），可缓存一天。
- 战力数据每天变化，建议缓存TTL设为4-6小时，避免频繁请求触发限流。
import time cache = {} def cached_query(hero_id, zone, query_type): key = f"{hero_id}_{zone}_{query_type}" if key in cache and time.time() - cache[key]["timestamp"] < 14400: # 4小时 return cache[key]["data"] data = query_power(hero_id=hero_id, zone=zone, query_type=query_type) cache[key] = {"data": data, "timestamp": time.time()} return data2. 请求重试机制
- 使用指数退避处理网络波动或429。
- 对于5xx错误最多重试3次，间隔1s、2s、4s。
3. 参数编码安全
- 当通过URL传递
hero参数时，中文需要进行URL编码（requests和fetch自动处理）。 - 如果直接拼接字符串，使用
encodeURIComponent或urllib.parse.quote。
4. 数据校验与异常处理
- 始终检查
code是否为0，不要直接信任HTTP状态码。 - 解析
rank_data前确认是否有该字段，避免KeyError。
参考文档
- 官方文档页：https://apizero.cn/aidocs/wzry
- 原始接口说明：https://apizero.cn/aidocs/wzry/raw.md