适用场景与典型用例王者荣耀全国战力查询API面向以下场景游戏数据工具开发小程序或网站展示英雄省/市/区战力排名。内容创作辅助快速获取英雄战力分布用于图文或视频数据支撑。个人学习与测试熟悉HTTP请求、JSON解析、限流控制等API工程实践。电竞分析按区服Android/iOS QQ/微信分析特定英雄的竞争强度。该API无需准备即可匿名调用每日50次适合个人和小型项目。接口能力边界核心功能英雄列表actionheroes返回130英雄的中文名、ename数字ID、称号和头像URL。数据源为腾讯官方https://pvp.qq.com/web201605/js/herolist.json实时性高。战力查询actionquery根据英雄和区服返回约90条省/市/区战力记录包含extreme各省/市/区的最低或最高战力及排名取决于type参数。similar与查询结果排名相近的其他地区排名差≤100。约束说明QPS5次/秒超过会返回429错误。请求方法仅支持GET。数据更新根据字段syn_date判断数据日期通常为当日或前一日。请求参数详解与鉴权Query参数必填与选填参数名必填类型说明示例action是string操作类型heroes英雄列表或query战力查询queryhero条件必填string英雄中文名如“赵云”actionquery时与hero_id二选一赵云hero_id条件必填number英雄ename数字ID如赵云107actionquery时二选一优先级高于hero107zone条件必填string区服代码aqqAndroid QQ,awxAndroid微信,iqqiOS QQ,iwxiOS微信aqqtype否string返回类型all完整列表默认、min最低战力、max最高战力min参数选择建议当英雄名称包含特殊字符或不确定时优先使用hero_idename避免编码问题。typemin可快速获取各等级的入门战力门槛typemax查看天花板all获取完整分布。Header参数鉴权参数名必填类型说明示例Authorization否stringAPI Key鉴权格式Bearer sk_live_xxx匿名调用可省略每日50次调用次数限制Bearer sk_live_xxxxxxxxxxxx无需鉴权即可调用但建议生产环境使用密钥以避免额度不足。可运行的请求示例1. 获取英雄列表curl -sS -X GET https://v1.apizero.cn/api/wzry?actionheroes | 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?actionqueryhero_id107zoneaqqtypemin | jq .参数说明hero_id107对应赵云zoneaqq为Android QQ区typemin返回最低战力数据。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, paramsparams, headersHEADERS) resp.raise_for_status() data resp.json() if data.get(code) 0: return data[data] else: raise Exception(fAPI error: {data.get(msg)}) def query_power(hero_nameNone, hero_idNone, zoneaqq, query_typemin): 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, paramsparams, headersHEADERS) resp.raise_for_status() return resp.json() # 示例查询赵云Android QQ区最低战力 result query_power(hero_id107) print(json.dumps(result, indent2, ensure_asciiFalse))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));返回值结构与字段解读以actionqueryhero_id107zoneaqqtypemin的响应为例节选{ 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 }核心字段解析字段路径类型说明codenumber0表示成功非0见错误码data.heroobject英雄基本信息name中文名、ename数字ID字符串、title称号、avatar头像URLdata.rank_data.extremeobject各级别的最低/最高战力详情包含province、city、district三个子对象extreme.*.addressstring地区完整名称格式如“云南”或“北京/朝阳区”extreme.*.ranknumber该级别的战力数值注意typemin时是最低战力typemax时是最高战力data.rank_data.similarobject与查询结果相近的其他地区仅当typemin或max时返回同省/市/区排名相差≤100的记录similar.provincearray省一级相近排名列表每个元素含address和rankdata.syn_datestring数据同步日期格式 yyyy-MM-dddata.typestring中文类型说明“最低战力”/“最高战力”/“完整列表”data.zoneobject区服信息code内部代码、platformQQ/微信、systemAndroid/iOS注意typeall时rank_data结构不同会返回一个完整的数组full_data包含约90条省/市/区战力记录按level混合排列。此时extreme和similar字段不存在。常见错误与排查方法错误表现可能原因解决方案HTTP 400缺少必填参数或参数格式错误检查action、zone、hero/hero_id是否提供zone仅允许aqq/awx/iqq/iwxHTTP 401Authorization格式错误或Key无效确认Header名称为Authorization值以Bearer开头HTTP 429请求频率超过QPS限制5次/秒加入本地限流使用setTimeout或time.sleep控制间隔≥200mscode1001英雄名称不存在或hero_id无效先调用actionheroes获取合法列表确认名称或ID正确code1002区服代码错误只使用aqq/awx/iqq/iwx四种code500服务器内部错误或数据源异常重试一次若持续失败可检查syn_date是否正常或联系支持返回数据中rank_data为空该英雄在该区服可能暂无排名数据新英雄或冷门区尝试更换typeall获取全部数据或更换区服工程化注意事项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_idhero_id, zonezone, query_typequery_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
