Skip to content
Public API · v1

Pokékipe Public API

免費的寶可夢競技分析，源自 Smogon 每月公開的使用統計，每月更新一次。輕度使用無需帳號；要批次拉取時，從帳號設定簽發個人金鑰即可拉高速率限制天花板。

  • 端點

    100+

  • 涵蓋格式

    30+

  • 更新

    每月

  • 認證

    選擇性

  • 授權

    CC BY 4.0

為什麼有它

這個 API 是什麼，又不是什麼

在向 /api/v1/ 寫下第一行程式碼之前，先了解這四件事。

這個 API 是什麼

面向全球寶可夢競技資料的唯讀 JSON 介面。問一句「這個月 Gen 9 OU 在 1500+ ELO 的 meta 是什麼？」或「這場賽事 Top Cut 裡誰剋制了這隻寶可夢？」，一次呼叫就能拿到答案，結構穩定且有完整文件。

資料從哪裡來

Smogon 的月度對戰紀錄（公開的 chaos JSON）、官方賽事資料源（Pokémon Company、VGC、Smogon Tour），以及 Limitless TCG 等社群運營賽事的社群來源。Pokékipe 在其上跑自家的擷取、正規化與加值管線，再以整理過的形態對外公開。

這個 API 不是什麼

它不是 Pokémon Showdown 的即時橋接，不是對戰模擬器，不是傷害計算器端點，也不是組隊引擎。那些工具都在網站本體裡，API 是它們腳下的資料層。

致謝上游

功勞歸於上游。Smogon、負責匯出 chaos 格式 JSON 的工具，以及每個月真正在打天梯的玩家社群，正是這份資料集存在的原因。Pokékipe 讓它可以被查詢，但底層資料並不屬於我們。

上手

30 秒內完成第一次呼叫

三段複製即用的範例，用來抓取格式列表。不需要 API 金鑰、不需要設定、不需要註冊。挑一個語言分頁，貼上，執行。

curl -s https://pokekipe.com/api/v1/formats \
  | jq '.[0:3]'

把路徑換成下方參考裡列出的任意端點即可。在快取預熱的情況下，第一次呼叫應該一秒內回來。

認證

認證與速率限制

匿名呼叫足以應付輕度使用。在帳號設定裡簽發的個人金鑰（免費），會為需要批次拉取資料的分析師與工具開發者拉高速率限制天花板。金鑰不會開啟新的端點，只是把上限拉高。

匿名，不帶金鑰

預設

什麼標頭都不帶就能呼叫。計數桶以 IP 為準，所以一個每個工作階段只發幾次請求的小腳本或 LLM 代理，永遠碰不到上限。

  • 不必帳號，不必註冊，也不用設定任何標頭。
  • 依 IP 計數，適合臨時腳本與 LLM 代理的工具呼叫。
  • 持續批次拉取會撞到 429，那就該換成個人金鑰了。

每分鐘

60

每天

5,000

已認證，使用個人金鑰

建議批次場景使用

把金鑰放到 X-API-Key 裡（或 Authorization: Bearer pk_live_…）。匿名呼叫仍然並行可用；金鑰只是拉高上限，不會開啟新端點。

  • 依使用者計數，IP 變了也不會重設計數器。
  • 每條路由的上限都更寬鬆。
  • 每個帳號最多 5 把活動金鑰，可隨時撤銷。

每分鐘

600

每天

100,000

每個回應都會帶的標頭

每個成功回應都會帶上下面這組速率限制標頭，讓用戶端不必重試也能自我節流。每次回應讀一次，等到 Remaining 只剩幾次時就提前減速，而不是等它歸零。

標頭意義
X-RateLimit-Tier你所屬的層級：匿名（沒有金鑰），或已認證（解析出 JWT 或 API 金鑰）。
X-RateLimit-Limit-Min你所屬層級的每分鐘上限（匿名 60，認證 600）。
X-RateLimit-Limit-Day你所屬層級的每日上限（匿名 5 000，認證 100 000）。
X-RateLimit-Remaining-Min目前 1 分鐘視窗剩餘的呼叫次數。接近 0 時就開始減速。
X-RateLimit-Remaining-Day目前 1 日視窗剩餘的呼叫次數。每天在固定的鐘錶時間重設。
Retry-After只在 429 時回傳。重試前等待這麼多秒，分鐘視窗通常不到 60。

錯誤

你可能會遇到的錯誤

標準 HTTP 狀態碼。回應主體永遠是 JSON，並帶有描述問題的 "detail" 欄位。請把 4xx 視為合約問題（你的請求），把 5xx 視為我們的問題（帶退避重試）。

200

OK

OK。回應主體就是參考裡記載的 JSON 負載。空陣列表示「沒有資料列」，而不是「欄位缺失」，請當作資料處理，不要當作失敗。

304

Not Modified

Not Modified。快取標頭驗證通過。直接沿用快取中的回應主體，不必重新解析。當你送出 If-None-Match 或 If-Modified-Since 時會自動回傳。

400

Bad Request

Bad Request。某個查詢參數或請求主體結構錯了。detail 訊息裡會點出具體欄位。在修正輸入之前不要重試。

401

Unauthorized

Unauthorized。請求需要 API 金鑰或工作階段，但兩者都沒拿到，或憑證已失效或被撤銷。別再原樣重送，重新簽發一份憑證。

404

Not Found

Not Found。路徑或資源不存在。對於以 Pokémon 為單位的路由，這通常表示該 Pokémon 在這個格式裡還沒有使用資料，而不是你拼錯。

429

Too Many Requests

Too Many Requests。你撞到了速率限制天花板。讀取 Retry-After 後等待。指數退避是種禮貌，但因為視窗很短，幾乎用不上。

500

Server Error

Internal Server Error。我們這邊出了狀況。等幾秒後重試一次；如果一直失敗，把請求 URL 帶到 Discord 上回報給我們。

503

Service Unavailable

Service Unavailable。我們正在部署，或暫時過載。請帶退避地重試。狀態更新會發布在社群 Discord 上。

基本規則

使用條款

四條基本規則。讀一次，給未來的自己省下一次 Discord 上的提問。

致謝上游

再散布或再發布時必須註明出處。請致謝 Pokékipe（附上 https://pokekipe.com 連結），同時為底層那份每月公開的 chaos JSON 致謝 Smogon。

盡力而為，沒有 SLA

盡力而為，沒有 SLA。資料按「現狀」提供，不保證可用性。請積極快取，端點變慢或回傳 429 時優雅降級。

版本管理

/api/v1/ 下的結構在 v1 生命週期內保持向後相容。破壞性變更會搬到 /api/v2/，並提前在 Discord 公告，舊路徑上加 sunset 標頭。

商業使用

商業使用在 CC BY 4.0 之下被允許。如果你基於這個 API 做了什麼，歡迎來社群 Discord 講講。

參考 · OpenAPI 3即時三欄

所有端點，集中在一個地方

逐一瀏覽每個端點，配套提供說明、參數表、請求與回應結構，以及 curl、JavaScript、Python 三種程式碼範例。一個搜尋框搜遍整套 API，可以深層連結到任意操作，URL 直接分享。

  • 100+ 端點
  • ·
  • 3-pane 導覽、內容、範例
  • ·
  • 全文搜尋
  • ·
  • 即時請求範例
或者直接拿原始的 OpenAPI 3 規格