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 をダウンロード

利用条件