WoS Atlas

API 参考

一个只读的普查 API。以下全部是 GET，密钥读到的内容与已登录用户完全一致，不会更多。

认证

把密钥放在两个标头中的任意一个里发送。没有别的方式能认证请求，发往未列于此处路由的密钥会被拒绝，而不会得到响应。

X-Api-Key: wos_YOUR_KEY

或者作为 bearer 令牌

Authorization: Bearer wos_YOUR_KEY

快速开始

把示例中的密钥换成你自己的。

curl -H "X-Api-Key: wos_YOUR_KEY" \ "https://api.wosatlas.com/v1/players/search?playerName=LordFrost"

端点

方法路径返回什么计为
GET/v1/alliances/{aid}/members获取一个联盟及其成员名单请求
GET/v1/alliances/leaderboard按实力总和为联盟排名请求
GET/v1/alliances/recruiting列出正在接受申请的联盟请求
GET/v1/alliances/search按标签或名称搜索联盟搜索
GET/v1/players/{uid}按内部 uid 获取一位领主请求
GET/v1/players/search按名称或领主 ID 搜索领主搜索

套餐与上限

当前的运行数值，并非固定权益。它们可能变化。

每项上限都按账号计算。多建密钥不会买到更多额度。

两个配额窗口都是滚动的，而非自然周期：读取窗口从当前时刻往回看三十天，搜索窗口往回看二十四小时。配额与搜索按账号计量而非按密钥计量——一个账号持有的每把密钥都从同一份额度中扣减。

响应标头

被正常响应的请求会带上全部这些标头，配额拒绝同样如此。峰值拒绝只带以 X-RateLimit 开头的三个标头，而在计量之前就被拒绝的请求——401 或 403——一个都不带。

标头含义
X-Quota-Limit该账号在滚动三十天窗口内的读取额度。
X-Quota-Remaining该窗口内剩余的读取次数。
X-Quota-Reset最早一次读取移出窗口的 Unix 秒数。
X-Search-Limit该账号在滚动二十四小时窗口内的搜索额度。
X-Search-Remaining该窗口内剩余的搜索次数。
X-Search-Reset最早一次搜索移出窗口的 Unix 秒数。
X-RateLimit-Limit该账号在短窗口内的峰值额度。
X-RateLimit-Remaining峰值窗口内剩余的请求数。
X-RateLimit-Reset峰值窗口翻转的 Unix 秒数。
Retry-After重试前应等待的秒数。每次 429 都会发送，且对应做出拒绝的那个窗口。

被拒绝时

有三种不同情况会以 429 回应，它们不可互换。

错误码发生了什么
QUOTA_EXCEEDED该账号滚动三十天的读取配额已用尽。`X-Quota-Remaining` 显示为零；`X-Search-Remaining` 仍然如实。
SEARCH_QUOTA_EXCEEDED该账号滚动二十四小时的搜索配额已用尽。`X-Search-Remaining` 显示为零；`X-Quota-Remaining` 仍然如实。只有两条搜索路由会计入其中。
RATE_LIMIT_EXCEEDED该账号的短时峰值窗口已满。`X-RateLimit-Remaining` 显示为零。这是秒级的上限，会自行释放；两个配额窗口都未被动用。

请依据 `error` 代码和 `Retry-After` 标头来决定是否重试，绝不要依据剩余计数器。按月拒绝和按日搜索拒绝都是 429，而且都会让另一个窗口的剩余计数器如实地保持非零，因此只盯着 `X-Quota-Remaining` 的客户端会看到 429 与一个很大的剩余值并列，进而断定服务器出了故障。

错误码

代码状态含义
INVALID_API_KEY401该密钥无法识别、已被吊销，或其所属账号已被删除。
ENDPOINT_NOT_ALLOWED403该路由不在开发者可用范围内。在范围之外的路由上出示密钥会被拒绝而不是得到响应，因此不要把密钥发往本文档未列出的端点。
QUOTA_EXCEEDED429该账号滚动三十天的读取配额已用尽。`X-Quota-Remaining` 显示为零；`X-Search-Remaining` 仍然如实。
SEARCH_QUOTA_EXCEEDED429该账号滚动二十四小时的搜索配额已用尽。`X-Search-Remaining` 显示为零；`X-Quota-Remaining` 仍然如实。只有两条搜索路由会计入其中。
RATE_LIMIT_EXCEEDED429该账号的短时峰值窗口已满。`X-RateLimit-Remaining` 显示为零。这是秒级的上限，会自行释放；两个配额窗口都未被动用。

机器可读规范

下面的 OpenAPI 文档由运行中的服务器生成，与本页所呈现的是同一份。

下载 openapi.json

条款