# Pokemon Showdown Battle API
> Competitive Pokémon battle data as an API, built on the open Pokémon Showdown dataset — the data that powers the popular online battle simulator. Look up any Pokémon by name for its National Dex number, types, base stats (HP, Attack, Defense, Sp. Atk, Sp. Def, Speed) and base-stat total, its regular and hidden abilities, gender ratio, egg groups, height, weight and evolution line, plus a sprite. Browse every Pokémon of a given type, and look up any battle move for its base power, accuracy, type, category (physical, special or status), PP, priority, target and effect — or filter moves by type and category. Pull a random Pokémon too. Real competitive data, no key needed upstream. Ideal for team builders, damage calculators, battle tools and Pokémon fan apps.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/pokemonshowdown-api/..."
```

## Pricing
- **Free** (Free) — 11,200 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 146,000 calls/Mo, 8 req/s
- **Pro** ($16/Mo) — 755,000 calls/Mo, 25 req/s
- **Mega** ($58/Mo) — 3,480,000 calls/Mo, 50 req/s

## Endpoints

### Pokemon

#### `GET /v1/pokemon` — A Pokemon by name, or a list by type

**Parameters:**
- `name` (query, optional, string) — Pokemon name, e.g. garchomp Example: `garchomp`
- `type` (query, optional, string) — Filter by type, e.g. dragon
- `limit` (query, optional, string) — Max results when listing (default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pokemonshowdown-api/v1/pokemon?name=garchomp&limit=30"
```

**Response:**
```json
{
    "data": {
        "pokemon": {
            "id": "garchomp",
            "num": 445,
            "evos": [],
            "name": "Garchomp",
            "color": "Blue",
            "prevo": "Gabite",
            "types": [
                "Dragon",
                "Ground"
            ],
            "sprite": "https://play.pokemonshowdown.com/sprites/dex/garchomp.png",
            "height_m": 1.9,
            "abilities": [
                {
                    "name": "Sand Veil",
                    "slot": "slot0"
                },
                {
                    "name": "Rough Skin",
                    "slot": "hidden"
                }
            ],
            "evo_level": 48,
            "weight_kg": 95,
            "base_stats": {
                "hp": 108,
                "speed": 102,
                "attack": 130,
                "defense": 95,
                "sp_attack": 80,
                "sp_defense": 85
            },
            "egg_groups": [
                "Monster",
                "Dragon"
            ],
            "base_stat_total": 600
        }
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:30.291Z",
        "request_id": "22dd7b33-f016-4f74-9af4-66b08a3a6be5"
    },
    "status": "ok",
    "message": "Pokemon retrieved successfully",
    "success": true
}
```

#### `GET /v1/random` — A random Pokemon

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pokemonshowdown-api/v1/random"
```

**Response:**
```json
{
    "data": {
        "pokemon": {
            "id": "steelixmega",
            "num": 208,
            "evos": [],
            "name": "Steelix-Mega",
            "color": "Gray",
            "types": [
                "Steel",
                "Ground"
            ],
            "sprite": "https://play.pokemonshowdown.com/sprites/dex/steelixmega.png",
            "height_m": 10.5,
            "abilities": [
                {
                    "name": "Sand Force",
                    "slot": "slot0"
                }
            ],
            "weight_kg": 740,
            "base_stats": {
                "hp": 75,
                "speed": 30,
                "attack": 125,
                "defense": 230,
                "sp_attack": 55,
                "sp_defense": 95
            },
            "egg_groups": [
                "Mineral"
            ],
            "base_stat_total": 610
        }
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:30.398Z",
        "request_id": "1ef43fbf-b177-446c-930a-c2cf8b1b30dc"
    },
    "status": "ok",
    "message": "Random Pokemon retrieved successfully",
    "success": true
}
```

### Moves

#### `GET /v1/move` — A single move by name

**Parameters:**
- `name` (query, required, string) — Move name, e.g. earthquake Example: `earthquake`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pokemonshowdown-api/v1/move?name=earthquake"
```

**Response:**
```json
{
    "data": {
        "move": {
            "id": "earthquake",
            "pp": 10,
            "num": 89,
            "is_z": false,
            "name": "Earthquake",
            "type": "Ground",
            "flags": [
                "protect",
                "mirror",
                "nonsky",
                "metronome"
            ],
            "is_max": false,
            "target": "allAdjacent",
            "accuracy": 100,
            "category": "Physical",
            "priority": 0,
            "base_power": 100,
            "description": "Hits adjacent Pokemon. Double damage on Dig."
        }
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:32.187Z",
        "request_id": "81e8b93e-334b-4f63-936a-9845c6f5c946"
    },
    "status": "ok",
    "message": "Move retrieved successfully",
    "success": true
}
```

#### `GET /v1/moves` — Moves filtered by type & category

**Parameters:**
- `type` (query, optional, string) — Move type, e.g. fire Example: `fire`
- `category` (query, optional, string) — physical | special | status Example: `special`
- `limit` (query, optional, string) — Max results (default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pokemonshowdown-api/v1/moves?type=fire&category=special&limit=30"
```

**Response:**
```json
{
    "data": {
        "type": "fire",
        "count": 26,
        "moves": [
            {
                "id": "blastburn",
                "pp": 5,
                "num": 307,
                "is_z": false,
                "name": "Blast Burn",
                "type": "Fire",
                "flags": [
                    "recharge",
                    "protect",
                    "mirror",
                    "metronome"
                ],
                "is_max": false,
                "target": "normal",
                "accuracy": 90,
                "category": "Special",
                "priority": 0,
                "base_power": 150,
                "description": "User cannot move next turn."
            },
            {
                "id": "eruption",
                "pp": 5,
                "num": 284,
                "is_z": false,
                "name": "Eruption",
                "type": "Fire",
                "flags": [
                    "protect",
                    "mirror",
                    "metronome"
                ],
                "is_max": false,
                "target": "allAdjacentFoes",
                "accuracy": 100,
                "category": "Special",
                "priority": 0,
                "base_power": 150,
                "description": "Less power as user's HP decreases. Hits foe(s)."
            },
            {
                "id": "mindblown",
                "pp": 5,
                "num": 720,
           
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service description & endpoints

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pokemonshowdown-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "pokemonshowdown-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/move": "A single move by name (name=, e.g. earthquake).",
            "GET /v1/moves": "Moves filtered by type & category (type=, category=physical|special|status, limit=).",
            "GET /v1/random": "A random Pokémon.",
            "GET /v1/pokemon": "A Pokémon by name, or a list filtered by type (name= | type=, limit=)."
        },
        "description": "Competitive Pokémon battle data via the open Pokémon Showdown dataset: every Pokémon with its base stats, types, abilities, gender ratio, egg groups and evolution line plus a sprite; and every battle move with base power, accuracy, type, category, PP, priority and effect. Filter Pokémon by type or moves by type and category. Real data, no key."
    },
    "meta": {
        "timestamp": "2026-06-08T01:18:32.393Z",
        "request_id": "eef5c1bf-3628-4760-8cd1-da4ba8b093ae"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/pokemonshowdown-api
OpenAPI spec: https://www.oanor.com/api/pokemonshowdown-api/openapi.json