王者荣耀战绩查询API：接口边界、参数详解与工程落地指南-尧图网络科技

适用场景分析

王者荣耀战绩查询API基于王者营地小程序接口封装，适合以下业务场景：

第三方玩家查战绩工具：输入游戏昵称即可展示排位赛、巅峰赛、娱乐模式的近期KDA、胜负场次。
电竞数据平台：批量抓取职业选手或高分段玩家的对局记录，用于赛后复盘或胜率统计。
战队管理后台：自动拉取队员的排位表现，生成周报或段位变动图。
直播弹幕机器人：观众发送“查战绩+昵称”，机器人实时返回该玩家最近战绩摘要。

该接口提供三种操作（action），覆盖从“找玩家”到“看战报”的完整链路，但需注意数据非实时（通常有数分钟延迟）以及单次请求仅支持单个玩家，不适合大规模并发爬取。

接口能力边界

三种操作与依赖关系

操作类型 (action)	功能说明	必需参数	输出数据量参考
`search`	根据昵称关键词搜索玩家	`keyword`（支持模糊匹配）	最多返回20个匹配结果
`roles`	查询某个玩家下的所有游戏角色	`user_id`（从search结果获取）	通常1-3个角色（微信/QQ区+安卓/iOS）
`battles`	获取某个角色的历史战绩	`user_id`+`role_id`+ 可选分页参数	每页约30条，最多请求3页

性能与延迟约束

QPS上限：每秒2次，超过会被限流（返回HTTP 429）。
数据新鲜度：返回的战绩非实时，可能滞后5-15分钟，不适用于实时对局监控。
翻页限制：battles操作通过last_time游标翻页，pages最大为3，即一次最多拉取约90条记录。若需更早数据，需多次请求并拼接。
跨区限制：search操作可能无法精确找到指定区服的玩家（如微信区vs QQ区），返回的玩家列表需二次筛选。

请求参数与鉴权

鉴权方式

在HTTP Header中携带X-API-Key，值为从API平台获取的密钥。示例：

X-API-Key: your_actual_api_key

请求体字段说明

请求体为JSON对象，字段如下（所有字段均为字符串或数字，无嵌套对象）：

{ "action": "search | roles | battles", "keyword": "玩家昵称（仅search时需要）", "user_id": "玩家唯一标识（roles/battles时需要）", "role_id": "角色ID（仅battles时需要）", "last_time": 0, // Unix时间戳，0表示获取最新 "option": 0, // 模式筛选：0全部 1排位 2巅峰 3娱乐 "pages": 1 // 拉取页数（1-3） }

注意：last_time、option、pages仅在action为battles时生效，其他操作中传这些字段会被忽略。

curl接入示例

以下三个示例展示完整请求链路，请将$APIZERO_API_KEY替换为真实密钥。

1. 根据昵称搜索玩家

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"search","keyword":"梦之泪伤"}' \ "https://v1.apizero.cn/api/wzry-battle"

2. 获取某个玩家的角色列表（user_id从上一步响应中提取）

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"roles","user_id":"78564321"}' \ "https://v1.apizero.cn/api/wzry-battle"

3. 查询某个角色的排位赛历史战绩（最近10场）

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"battles","user_id":"78564321","role_id":"128903","option":1,"last_time":0,"pages":1}' \ "https://v1.apizero.cn/api/wzry-battle"

Python代码接入

使用requests库封装一个简洁的查询类，便于集成到项目：

import requests class WzryBattleAPI: BASE_URL = "https://v1.apizero.cn/api/wzry-battle" def __init__(self, api_key: str): self.headers = { "X-API-Key": api_key, "Content-Type": "application/json" } def search_player(self, keyword: str) -> dict: """搜索玩家，返回匹配玩家列表""" payload = {"action": "search", "keyword": keyword} resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() def get_roles(self, user_id: str) -> dict: """获取玩家角色列表""" payload = {"action": "roles", "user_id": user_id} resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() def get_battles(self, user_id: str, role_id: str, option: int = 0, last_time: int = 0, pages: int = 1) -> dict: """获取战绩列表""" payload = { "action": "battles", "user_id": user_id, "role_id": role_id, "option": option, "last_time": last_time, "pages": pages } resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() # 使用示例 if __name__ == "__main__": api = WzryBattleAPI("your_api_key_here") # 第一步：搜索 search_res = api.search_player("花木兰") print("搜索结果:", search_res) # 实际使用时需从data字段中提取user_id

注意：以上代码未处理错误和限流，生产环境需增加重试和退避逻辑。

返回值结构解读

所有操作均返回如下顶层结构：

{ "code": 200, "data": {}, "message": "success" }

code：200表示成功，非200表示出错（参考错误列表）。
message：请求状态描述。
data：具体数据，不同操作字段差异较大。
- search：data通常包含player_list数组，每个元素含user_id、nickname、avatar_url等。
- roles：data包含role_list数组，每个元素含role_id、role_name、area（微信/QQ）、platform（安卓/iOS）、level等。
- battles：data包含battle_list数组和next_time（下次翻页游标），每条记录含英雄名、KDA、胜负、模式、时间戳等。

由于原始文档未提供完整的字段清单，具体键名请以实际响应或官方文档为准。建议先调用一次search获取响应后再解析。

常见错误与排查

HTTP状态码	错误含义	典型原因	处理方式
400	请求参数错误	action缺失或无效，必需参数未传	检查请求体JSON是否完整
401	未授权	API Key未提供或格式错误	确认Header中包含`X-API-Key`且值为有效密钥
403	权限拒绝	API Key过期或未绑定该接口	重新生成API Key并确认接口权限
404	资源未找到	search时玩家不存在，或battles时role_id无效	提示用户检查昵称/ID是否正确
429	请求频率超限	每秒请求超过2次	加入至少500ms的间隔；使用令牌桶限流
500	服务器内部错误	临时故障或依赖服务异常	等待后重试；若持续出现需联系平台支持