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

條款