王者荣耀全国战力查询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参数（必填与选填）

参数选择建议：

• 当英雄名称包含特殊字符或不确定时，优先使用hero_id（ename），避免编码问题。
• type=min可快速获取各等级的入门战力门槛，type=max查看天花板，all获取完整分布。

Header参数（鉴权）

无需鉴权即可调用，但建议生产环境使用密钥以避免额度不足。

可运行的请求示例

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" }

核心字段解析：

注意：type=all时，rank_data结构不同，会返回一个完整的数组full_data，包含约90条省/市/区战力记录（按level混合排列）。此时extreme和similar字段不存在。

常见错误与排查方法

工程化注意事项

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 data

2. 请求重试机制

• 使用指数退避处理网络波动或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