王者荣耀战绩查询API实战：搜索玩家、查看角色与历史战报

适用场景当开发者需要将王者荣耀战绩数据集成到自己的应用中时例如战队数据看板自动拉取队员近期的排位赛、巅峰赛表现生成 KDA 统计报表直播辅助工具主播输入玩家昵称实时展示当前段位和历史战报个人复盘工具支持多维度筛选排位/巅峰/娱乐按时间翻页拉取对局详情社区 Bot在聊天群内通过指令查询玩家战绩无需手动打开游戏或营地该 API 通过模拟王者营地的内部接口实现数据获取使用时应遵守平台使用规范避免高频调用导致 IP 被封。接口能力边界能力分类说明搜索玩家根据昵称关键词模糊匹配返回 userId、头像、近期使用英雄等概要角色列表通过 userId 查询该账号下的所有角色通常只有一个及对应 roleId、大区、段位历史战绩通过 roleId 拉取对局记录支持排位/巅峰/娱乐筛选支持翻页最多 3 页每页约 30 条QPS 限制2 请求/秒超出会返回 429 或限流提示注意战绩数据来源于王者营地接口非官方标准接口存在因王者营地升级导致数据不可用的风险。不建议用于关键业务。参数与鉴权鉴权方式请求时需要在 Header 中携带X-API-Key其值为平台分配的 API Key。请妥善保管不要泄露在公开仓库中。请求地址POST https://v1.apizero.cn/api/wzry-battle请求体参数请求体为 JSON 对象所有参数均置于顶层字段中参数名类型必填描述适用 actionactionstring是操作类型search/roles/battles全部keywordstring否玩家昵称关键词仅 search 时使用searchuser_idstring否玩家 userIdsearch 阶段可获取roles / battlesrole_idstring否角色 roleIdroles 阶段可获取battleslast_timenumber否翻页游标Unix 时间戳0 表示最新battlesoptionnumber否模式筛选0全部 1排位 2巅峰 3娱乐battlespagesnumber否拉取页数1~3默认 1battles三步调用流程search用昵称关键词搜索玩家得到基础信息含 userIdroles用 userId 获取角色列表得到一个或多个角色含 roleId、段位、区服battles用 roleId 拉取历史战绩可指定模式和翻页curl 接入示例以下示例假设已设置环境变量APIZERO_API_KEY。第一步搜索玩家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返回示例节选{ code: 200, message: success, data: [ { user_id: 123456789, nickname: 梦泪, avatar: https://xxx, level: 30, hero_usage: [李白, 韩信, 曜] } ] }第二步获取角色列表使用上一步得到的user_idcurl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:roles,user_id:123456789} \ https://v1.apizero.cn/api/wzry-battle返回示例{ code: 200, data: [ { role_id: wzry_98765, role_name: 梦泪, area: 微信iOS区, rank: 最强王者, star: 50 } ] }第三步拉取历史战绩最近排位赛curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:battles,user_id:123456789,role_id:wzry_98765,option:1,pages:2,last_time:0} \ https://v1.apizero.cn/api/wzry-battle参数说明option1仅拉排位赛pages2拉取两页约 60 条last_time0从最新开始。Python 接入示例import requests import json API_URL https://v1.apizero.cn/api/wzry-battle API_KEY your_api_key_here # 替换为真实密钥 def search_player(keyword: str) - list: payload {action: search, keyword: keyword} resp requests.post(API_URL, jsonpayload, headers{X-API-Key: API_KEY}) return resp.json().get(data, []) def get_roles(user_id: str) - list: payload {action: roles, user_id: user_id} resp requests.post(API_URL, jsonpayload, headers{X-API-Key: API_KEY}) return resp.json().get(data, []) def get_battles(user_id: str, role_id: str, option: int 0, pages: int 1, last_time: int 0) - list: payload { action: battles, user_id: user_id, role_id: role_id, option: option, pages: pages, last_time: last_time } resp requests.post(API_URL, jsonpayload, headers{X-API-Key: API_KEY}) return resp.json().get(data, []) if __name__ __main__: # 搜索 players search_player(梦泪) if not players: print(未找到玩家) exit() user players[0] print(f找到玩家{user[nickname]} (userId: {user[user_id]})) # 获取角色 roles get_roles(user[user_id]) if not roles: print(无角色) exit() role roles[0] print(f角色{role[role_name]}段位{role[rank]}) # 拉取最近排位战报 battles get_battles(user[user_id], role[role_id], option1, pages1) print(f获取到 {len(battles)} 条战报记录)返回字段解读通用响应结构{ code: 200, message: success, data: [...] }字段类型说明codenumber业务状态码200 为成功messagestring状态描述dataarray具体数据结构随 action 不同而异search 返回的 data 内字段字段类型说明user_idstring玩家唯一标识nicknamestring昵称avatarstring头像 URLlevelnumber游戏等级hero_usagearray近期常用英雄列表字符串roles 返回的 data 内字段字段类型说明role_idstring角色 ID用于 battlesrole_namestring角色名通常等于昵称areastring所在大区与系统rankstring当前段位文字描述starnumber当前星数battles 返回的 data 内字段每个 battle 对象示例以实际返回为准大致包含字段类型说明game_idstring对局 IDhero_namestring使用英雄killnumber击杀数deathnumber死亡数assistnumber助攻数kdanumber评分如 10.5resultstring结果win/losemodestring模式排位/巅峰/娱乐timenumber对局时间戳equipmentarray出装mvpboolean是否 MVP若有具体字段名和类型请以实际接口返回为准建议先打印一次了解结构。常见错误与排查错误现象可能原因解决措施HTTP 401API Key 未携带或无效检查X-API-Key是否正确HTTP 429请求超过 QPS 2/s添加请求节流如 time.sleep(0.5)code!200业务级别错误如参数不合法查看 message 字段常见缺少必填参数、keyword 为空、user_id 不存在data 为空数组未匹配到玩家/no roles/no battles检查参数search 时关键词太短userId 错误battles 返回只有第一页pages 参数未传或值不在 1~3 之间明确传 pages 并确保在范围内last_time 参数无效传入了非数值或负数传 0 表示最新或传上一条 battle 的时间戳减 1工程化注意事项速率控制API 限制 2 QPS建议在客户端实现 token bucket 或请求队列避免限流后重试导致恶性循环。缓存策略玩家基础信息userId、roleId变更频率低可缓存 5~10 分钟战报数据可缓存 30~60 秒。减少重复请求。错误重试遇到 429 或 5xx 时使用指数退避重试初始 1s最大 10s最多重试 3 次。API Key 管理不要硬编码使用环境变量或密钥管理服务。Git 提交前检查是否有密钥泄露。数据稳定性该接口依赖第三方未公开 API随时可能失效。建议设计降级方案例如返回缓存数据或提示“服务暂不可用”。日志记录记录每次请求的 action、参数、响应状态码和耗时便于排查线上问题。参数校验在前端或调用入口对 keyword 长度、pages 范围、option 值做校验减少无效请求。参考文档官方文档页https://apizero.cn/aidocs/wzry-battle原始文档可查看完整参数与响应示例https://apizero.cn/aidocs/wzry-battle/raw.md