PokePicker API

A free, public REST API for Pokémon data — ideal for side projects, prototypes, demos, and educational use.

The PokePicker API exposes the same clean, normalized Pokémon data that powers this site. The public tier requires no API key and is suitable for low-to-medium traffic clients such as bots, classroom demos, and frontend prototypes. All responses are JSON and delivered over HTTPS.

Base URL

All endpoints are relative to the versioned base below. Always use HTTPS — plain HTTP requests are redirected but discouraged.

https://api.pokepicker.app/api/v1

Endpoints

GET /api/v1/pokemon/random — returns a single random Pokémon.
GET /api/v1/pokemon/random?count=6 — returns a random team of up to 6 Pokémon. count must be between 1 and 6.
GET /api/v1/pokemon/:id — returns a single Pokémon by its National Pokédex ID (1–1025).
GET /api/v1/pokemon?generation=1&type=fire — returns a filtered, paginated list of Pokémon.

Query Parameters

All query parameters are optional and case-insensitive unless noted. Combine them freely; an empty filter set returns the default list.

Parameter	Type	Description
generation	integer 1–9	Filter by generation.
type	string	Filter by primary or secondary type (e.g. fire, water, grass).
count	integer	Number of results to return (max 100). Default 20.
legendary	boolean	If true, only legendary Pokémon.
shiny	boolean	If true, return shiny sprite URLs.
starter	boolean	If true, only starter Pokémon.

Response Format

All responses are JSON with a 200 OK status on success. A single Pokémon object looks like:

{
  "id": 25,
  "name": "pikachu",
  "types": ["electric"],
  "generation": 1,
  "height": 4,
  "weight": 60,
  "abilities": ["static", "lightning-rod"],
  "sprite": "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png",
  "weaknesses": ["ground"]
}

List endpoints return an object with a results array and pagination cursors (next, previous).

Rate Limiting

The public API is limited to 100 requests per minute per IP to keep the service free and stable. When the limit is exceeded, the API responds with 429 Too Many Requests and a Retry-After header (in seconds) indicating when to retry. Cache responses client-side where possible, and consider backing off exponentially on 429. For higher limits, please contact us.

Error Handling

400 Bad Request — invalid query parameter.
404 Not Found — Pokémon ID or endpoint not found.
429 Too Many Requests — rate limit exceeded.
500 Internal Server Error — server error, retry with backoff.

Examples

curl

curl "https://api.pokepicker.app/api/v1/pokemon/random"

JavaScript (fetch)

const res = await fetch(
  "https://api.pokepicker.app/api/v1/pokemon/random?count=6"
);
const team = await res.json();
console.log(team);

Python (requests)

import requests

res = requests.get(
    "https://api.pokepicker.app/api/v1/pokemon",
    params={"generation": 1, "type": "fire"},
)
data = res.json()
print(data)

Use Cases

The API is designed for lightweight, read-heavy workloads. Common use cases include:

Daily Pokémon widgets for personal dashboards.
Random team generators for fan sites and Discord bots.
Type-effectiveness demos in programming tutorials.
Prototyping frontends that need realistic, structured sample data.

Versioning

The API is versioned via the URL path (v1). Breaking changes will be published under a new version, leaving v1 consumers unaffected. Deprecation notices will appear in this document at least 90 days before removal.

Status

The PokePicker API is currently in a documentation-only phase. The endpoints above describe the planned public API; the actual implementation is on the roadmap. Once live, this page will reflect real response data. For updates or questions, contact us.