Skip to content
Public API · v1

Pokékipe Public API

Analytics Pokémon competitive miễn phí, dẫn xuất từ usage stats hàng tháng của Smogon và refresh mỗi tháng. Không cần tài khoản cho usage thường ngày; mint một key cá nhân từ Account Settings để nâng trần rate-limit cho bulk pull.

QuickstartMở reference

  • Endpoint

    100+

  • Format

    30+

  • Refresh

    Hàng tháng

  • Auth

    Tùy chọn

  • License

    CC BY 4.0

Tại sao thứ này tồn tại

API này là gì, và không phải là gì

Bốn điều cần biết trước khi viết một dòng code chống lại /api/v1/.

API này là gì

Một surface JSON read-only trên data Pokémon competitive của thế giới. Hỏi "meta Gen 9 OU tại 1500+ ELO tháng này thế nào?" hoặc "ai counter Pokémon này trong top cut tournament này?" và lấy câu trả lời single-call với shape ổn định, có docs.

Data đến từ đâu

Battle log hàng tháng của Smogon (chaos JSON public), feed tournament chính thức (Pokémon Company, VGC, Smogon Tour), và nguồn community như Limitless TCG cho event do community vận hành. Pokékipe chạy pipeline ingestion, normalization, và enrichment riêng trên đó, rồi re-expose kết quả đã làm sạch.

API này KHÔNG phải gì

Không phải bridge Pokémon Showdown live, không phải simulator trận đấu, không phải endpoint damage calculator, không phải engine teambuilding. Mấy tool đó sống trên website. API là tầng data chúng ngồi trên.

Credit upstream

Credit đúng người đúng việc. Smogon, các exporter chaos-format JSON, và cộng đồng player chơi mỗi tháng là lý do dataset này tồn tại. Pokékipe làm nó có thể truy vấn được; không sở hữu data gốc.

Bắt đầu

Call đầu tiên của bạn, trong 30 giây

Ba ví dụ copy-paste fetch catalog format. Không API key, không setup, không signup. Chọn tab ngôn ngữ, paste, chạy.

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

Thay path bằng bất kỳ endpoint nào trong reference dưới đây. Call đầu tiên nên trả về dưới một giây trên cache nóng.

Xác thực

Xác thực và rate limit

Các lệnh gọi ẩn danh hoạt động cho usage thường ngày. Một key cá nhân (miễn phí, tạo từ cài đặt tài khoản) nâng trần rate-limit cho analyst và builder kéo data hàng loạt. Key không bao giờ mở khóa endpoint mới; chúng chỉ nâng trần.

Ẩn danh, không key

Mặc định

Gọi mà không cần header. Bucket khóa trên IP của bạn, nên một script nhỏ hoặc agent LLM bắn một nắm request per session sẽ không bao giờ trip limit.

  • Không account, không signup, không header phải set.
  • Bucket per-IP, phù hợp cho script ad-hoc và tool-use agent LLM.
  • Dính 429 nếu bạn duy trì bulk pull; switch sang key cá nhân.

mỗi phút

60

mỗi ngày

5,000

Đã xác thực, với key cá nhân

Khuyên dùng cho bulk

Pass key của bạn dưới dạng X-API-Key (hoặc Authorization: Bearer pk_live_…). Call ẩn danh vẫn chạy song song; key chỉ nâng trần, không mở khóa endpoint mới.

  • Bucket per-user: IP đổi không reset count.
  • Trần cao hơn trên mọi limit per-route.
  • Tối đa 5 key active per account, revoke bất cứ lúc nào.

mỗi phút

600

mỗi ngày

100,000

Tạo API key

Header trên mỗi response

Mỗi response thành công đều mang theo rate-limit header dưới đây để client của bạn tự pace mà không cần retry. Đọc một lần per response và back off ngay khi Remaining còn vài request, không phải zero.

HeaderÝ nghĩa
X-RateLimit-TierBạn thuộc tier nào: ẩn danh (no key) hoặc đã xác thực (JWT hoặc API key đã resolve).
X-RateLimit-Limit-MinTrần per-minute cho tier của bạn (60 ẩn danh, 600 đã xác thực).
X-RateLimit-Limit-DayTrần per-day cho tier của bạn (5 000 ẩn danh, 100 000 đã xác thực).
X-RateLimit-Remaining-MinSố call còn lại trong window phút hiện tại. Chậm lại khi gần zero.
X-RateLimit-Remaining-DaySố call còn lại trong window ngày hiện tại. Reset cùng wall-clock minute mỗi ngày.
Retry-AfterChỉ gửi trên 429. Chờ chừng đó giây trước khi retry, thường dưới 60 cho window per-minute.

Lỗi

Các lỗi có thể gặp

Status code HTTP chuẩn. Body luôn là JSON với field "detail" mô tả lỗi. Coi 4xx là vấn đề contract (request của bạn) và 5xx là vấn đề của chúng tôi (retry với backoff).

200

OK

OK. Body là payload JSON như docs trong reference. Mảng rỗng nghĩa là "không có row", không phải "thiếu", xử lý như data chứ không phải fail.

304

Not Modified

Not Modified. Cache header đã được validate. Dùng body đã cache, không cần parse lại. Trả về tự động khi bạn gửi If-None-Match hoặc If-Modified-Since.

400

Bad Request

Bad Request. Một query param hoặc body shape sai. Detail message chỉ rõ field cụ thể. Đừng retry mà chưa fix input.

401

Unauthorized

Unauthorized. Request cần API key hoặc session mà không có cái nào, hoặc credential bị invalid/revoke. Đừng bắn liên tục, cấp lại credential.

404

Not Found

Not Found. Path hoặc resource không tồn tại. Với route per-Pokémon, thường nghĩa là format đó chưa có usage data cho Pokémon đó, không phải bạn typo.

429

Too Many Requests

Too Many Requests. Bạn chạm trần rate-limit. Đọc Retry-After và chờ, exponential backoff là phép lịch sự nhưng hiếm khi cần vì window ngắn.

500

Server Error

Internal Server Error. Có cái gì đó nổ phía chúng tôi. Retry một lần sau vài giây; nếu vẫn lỗi, ping chúng tôi trên Discord kèm URL request.

503

Service Unavailable

Service Unavailable. Chúng tôi đang deploy hoặc tạm thời quá tải. Retry với backoff. Status update post trên Discord community.

Luật chơi

Điều khoản sử dụng

Bốn luật chơi. Đọc một lần, tự cứu bản thân tương lai một cú ping Discord.

Credit upstream

Bắt buộc attribution khi redistribute hoặc republish. Credit Pokékipe (link đến https://pokekipe.com), và credit Smogon cho chaos JSON gốc họ publish mỗi tháng.

Best-effort, no SLA

Best-effort, no SLA. Data được serve "as is" không có guarantee uptime. Cache aggressive và degrade gracefully khi endpoint chậm hoặc trả 429.

Versioning

Schema dưới /api/v1/ giữ backwards-compatible trong vòng đời v1. Breaking change đi vào /api/v2/ với thông báo trước trên Discord và sunset header trên path deprecated.

Use thương mại

Use thương mại được phép dưới CC BY 4.0. Nếu bạn build cái gì trên API này, chúng tôi rất muốn nghe về nó trên Discord community.

Reference · OpenAPI 3Live, ba pane

Duyệt mọi endpoint, tất cả tại một chỗ

Duyệt mọi endpoint với mô tả, bảng parameter, schema request và response, và code sample trong curl, JavaScript, và Python. Search toàn bộ API trong một ô, deep-link đến mọi operation, share URL.

  • 100+ endpoint
  • ·
  • 3-pane navigation, content, sample
  • ·
  • full-text search
  • ·
  • sample request live
Mở reference đầy đủHoặc lấy spec OpenAPI 3 raw