API publique · v1

API publique Pokékipe

API analytique compétitive Pokémon, gratuite, dérivée des stats mensuelles publiées par Smogon et rafraîchie chaque mois. Pas besoin de compte pour un usage occasionnel ; génère une clé personnelle depuis tes paramètres pour relever le plafond de rate-limit sur les pulls en volume.

Endpoints
100+
Formats couverts
30+
Mise à jour
Mensuelle
Auth
Optionnelle
Licence
CC BY 4.0

Pourquoi ça existe

Ce que cette API est, et ce qu'elle n'est pas

Quatre choses à savoir avant d'écrire la moindre ligne de code contre /api/v1/.

Ce que cette API est

Une surface JSON en lecture seule sur les données Pokémon compétitif mondiales. Pose « quel est le meta de la Gen 9 OU à 1500+ ELO ce mois-ci ? » ou « qui a counter ce Pokémon dans le top cut de ce tournoi ? », et obtiens une réponse en un seul appel avec des shapes stables et documentées.

D'où viennent les données

Les battle logs mensuels de Smogon (le chaos JSON public), les feeds officiels de tournois (Pokémon Company, VGC, Smogon Tour), et des sources communautaires comme Limitless TCG pour les events community-run. Pokékipe fait sa propre ingestion, normalisation et enrichissement par-dessus, puis ré-expose le résultat propre.

Ce que cette API n'est pas

Pas un pont live vers Pokémon Showdown, pas un simulateur de combat, pas un endpoint de damage calculator, pas un moteur de teambuilding. Ces outils vivent sur le site. L'API est la couche data en dessous.

Crédit aux sources

Tout le crédit revient aux sources. Smogon, les exporteurs du format chaos JSON, et la communauté de joueurs qui jouent les ladders chaque mois sont la raison pour laquelle ce dataset existe. Pokékipe rend la donnée interrogeable, mais ne possède pas la donnée brute.

Démarrer

Ton premier appel, en 30 secondes

Trois exemples copy-paste qui fetchent le catalogue de formats. Pas de clé API, pas de setup, pas de signup. Choisis ton onglet, colle, lance.

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

Remplace le path par n'importe quel endpoint listé dans la référence ci-dessous. Le premier appel doit revenir en moins d'une seconde sur cache chaud.

Authentification

Authentification et limites de débit

Les appels anonymes fonctionnent pour un usage occasionnel. Une clé personnelle (gratuite, générée depuis tes paramètres de compte) relève le plafond de rate-limit pour les analystes et les outils tiers qui pullent des données en volume. Une clé ne déverrouille jamais d'endpoints supplémentaires, elle relève seulement le plafond.

Anonyme, sans clé

Par défaut

Fais tes appels sans aucun header. Le bucket est indexé sur ton IP, donc un petit script ou un agent LLM faisant quelques requêtes par session ne déclenchera jamais la limite.

Pas de compte, pas de signup, aucun header à passer.
Bucket par IP, parfait pour scripts ad-hoc et tool-use d'agents LLM.
Tape un 429 si tu enchaînes des pulls en volume ; passe alors sur une clé personnelle.

par minute

par jour

5,000

Authentifié, avec une clé personnelle

Recommandé pour le volume

Passe ta clé via X-API-Key (ou Authorization: Bearer pk_live_…). Les appels anonymes continuent à fonctionner en parallèle ; la clé ne fait que relever le plafond, elle ne déverrouille pas de nouveaux endpoints.

Bucket par utilisateur : tes changements d'IP ne reset pas le compteur.
Plafonds plus généreux sur chaque limite per-route.
Jusqu'à 5 clés actives par compte, révocables à tout moment.

par minute

600

par jour

100,000

Headers sur chaque réponse

Chaque réponse 2xx porte les headers de rate-limit ci-dessous, pour que ton client puisse se réguler sans retry. Lis-les une fois par réponse et ralentis dès que Remaining approche zéro, pas après.

Header	Signification
X-RateLimit-Tier	Le palier qui te concerne : anonyme (sans clé) ou authentifié (JWT ou clé API résolue).
X-RateLimit-Limit-Min	Plafond par minute pour ton palier (60 anonyme, 600 authentifié).
X-RateLimit-Limit-Day	Plafond par jour pour ton palier (5 000 anonyme, 100 000 authentifié).
X-RateLimit-Remaining-Min	Appels restants dans la fenêtre minute courante. Ralentis quand ça approche de zéro.
X-RateLimit-Remaining-Day	Appels restants dans la fenêtre jour courante. Reset à la même heure pile chaque jour.
Retry-After	Envoyé uniquement sur 429. Attends ce nombre de secondes avant de retry — souvent moins de 60 pour la fenêtre minute.

Erreurs

Les erreurs que tu pourras voir

Codes HTTP standards. Le body est toujours du JSON avec un champ "detail" qui décrit le problème. Traite les 4xx comme un problème de contrat (ta requête) et les 5xx comme un problème de notre côté (retry avec backoff).

200

OK. Le body est le JSON documenté dans la référence. Un array vide signifie « pas de lignes », pas « manquant » — traite-le comme de la donnée, pas comme un échec.

304

Not Modified

Not Modified. Les headers de cache ont été validés. Utilise ton body en cache, pas besoin de re-parse. Renvoyé automatiquement quand tu envoies If-None-Match ou If-Modified-Since.

400

Bad Request

Bad Request. Un paramètre de query ou un shape de body est invalide. Le message detail nomme le champ exact. Ne retry pas sans corriger l'input.

401

Unauthorized

Unauthorized. La requête nécessitait une clé API ou une session, et n'en a reçu aucune valide, ou la clé/session est révoquée. Ne re-tire pas en boucle — re-mint le credential.

404

Not Found

Not Found. Le path ou la ressource n'existe pas. Pour les routes par-Pokémon, ça signifie souvent que le format n'a pas encore de données d'usage pour ce Pokémon, pas une faute de frappe de ton côté.

429

Too Many Requests

Too Many Requests. Tu as touché le plafond de rate-limit. Lis Retry-After et attends — un backoff exponentiel est de bon ton mais rarement nécessaire vu la fenêtre courte.

500

Server Error

Internal Server Error. Quelque chose a planté chez nous. Retry une fois après quelques secondes ; si ça persiste, ping-nous sur Discord avec l'URL de la requête.

503

Service Unavailable

Service Unavailable. On déploie ou on est temporairement surchargé. Retry avec backoff. Les statuts sont postés sur le Discord communautaire.

Règles du jeu

Conditions d'utilisation

Quatre règles de base. Lis une fois, ça t'évite un ping Discord plus tard.

Crédit aux sources

Attribution requise lors de la redistribution ou de la republication. Credite Pokékipe (lien vers https://pokekipe.com), et credite Smogon pour le chaos JSON qu'ils publient chaque mois.

Best-effort, pas de SLA

Best-effort, pas de SLA. La donnée est servie « as is » sans garantie d'uptime. Cache agressivement et dégrade gracieusement quand un endpoint est lent ou répond 429.

Versioning

Les schémas sous /api/v1/ restent rétro-compatibles pendant le cycle de vie de la v1. Les changements breaking vont sur /api/v2/ avec un préavis sur Discord et un header sunset sur le path déprécié.

Usage commercial

L'usage commercial est autorisé sous CC BY 4.0. Si tu construis quelque chose au-dessus de cette API, on serait ravis d'en entendre parler sur le Discord communautaire.

Référence · OpenAPI 3Live, trois colonnes

Parcourir chaque endpoint, tout au même endroit

Parcours chaque endpoint avec descriptions, tableaux de paramètres, schémas de requête et de réponse, et exemples de code en curl, JavaScript et Python. Recherche dans toute l'API en une seule barre, deep-link vers n'importe quelle opération, partage l'URL.

100+ endpoints
·
3-pane navigation, contenu, samples
·
recherche plein texte
·
exemples de requêtes live

Ou récupère la spec OpenAPI 3 brute