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 规范