# Chess Openings API
> The Encyclopaedia of Chess Openings (ECO) as an API — 3,161 named chess openings and variations with their ECO code (A00–E99), full name, family/variation and the exact move sequence (PGN and a clean move list). Search openings by name, ECO code or ECO volume; list every opening under a code (e.g. B20 → 27 Sicilian lines); pick a random opening; and — the killer feature — identify which opening a game is in from a sequence of moves (e.g. "1. e4 c5 2. Nf3" → Sicilian Defense). Ideal for chess apps, game analysis, training tools, bots and trivia. Open data from the lichess-org/chess-openings project.

## 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/chessopenings-api/..."
```

## Pricing
- **Free** (Free) — 3,600 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 49,500 calls/Mo, 8 req/s
- **Pro** ($13/Mo) — 243,000 calls/Mo, 20 req/s
- **Mega** ($34/Mo) — 1,205,000 calls/Mo, 50 req/s

## Endpoints

### Chess Openings

#### `GET /v1/eco` — All openings with a given ECO code

**Parameters:**
- `code` (query, required, string) — ECO code, e.g. B20 Example: `B20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chessopenings-api/v1/eco?code=B20"
```

**Response:**
```json
{
    "data": {
        "eco": "B20",
        "count": 27,
        "openings": [
            {
                "eco": "B20",
                "pgn": "1. e4 c5",
                "ply": 2,
                "name": "Sicilian Defense",
                "moves": [
                    "e4",
                    "c5"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": null
            },
            {
                "eco": "B20",
                "pgn": "1. e4 c5 2. Qg4",
                "ply": 3,
                "name": "Sicilian Defense: Amazon Attack",
                "moves": [
                    "e4",
                    "c5",
                    "Qg4"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": "Amazon Attack"
            },
            {
                "eco": "B20",
                "pgn": "1. e4 c5 2. d3 Nc6 3. c3 d6 4. f4",
                "ply": 7,
                "name": "Sicilian Defense: Big Clamp Formation",
                "moves": [
                    "e4",
                    "c5",
                    "d3",
                    "Nc6",
                    "c3",
                    "d6",
                    "f4"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": "Big Clamp Formation"
            },
            {
                "eco": "B20",
     
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/identify` — Identify the opening from a move sequence

**Parameters:**
- `moves` (query, required, string) — Moves in SAN/PGN, e.g. 1. e4 c5 2. Nf3 Example: `1. e4 c5 2. Nf3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chessopenings-api/v1/identify?moves=1.+e4+c5+2.+Nf3"
```

**Response:**
```json
{
    "data": {
        "exact": false,
        "opening": {
            "eco": "B20",
            "pgn": "1. e4 c5",
            "ply": 2,
            "name": "Sicilian Defense",
            "moves": [
                "e4",
                "c5"
            ],
            "family": "Sicilian Defense",
            "volume": "B",
            "variation": null
        },
        "input_ply": 3,
        "matched_ply": 2
    },
    "meta": {
        "timestamp": "2026-05-31T09:34:54.905Z",
        "request_id": "4430efd6-380c-4014-ab15-5c3665121029"
    },
    "status": "ok",
    "message": "Opening identified",
    "success": true
}
```

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

**Parameters:**
- `volume` (query, optional, string) — Restrict to ECO volume A-E

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

**Response:**
```json
{
    "data": {
        "opening": {
            "eco": "E36",
            "pgn": "1. d4 Nf6 2. c4 e6 3. Nc3 Bb4 4. Qc2 d5 5. a3 Bxc3+ 6. Qxc3 Ne4",
            "ply": 12,
            "name": "Nimzo-Indian Defense: Classical Variation, Noa Variation, Main Line",
            "moves": [
                "d4",
                "Nf6",
                "c4",
                "e6",
                "Nc3",
                "Bb4",
                "Qc2",
                "d5",
                "a3",
                "Bxc3+",
                "Qxc3",
                "Ne4"
            ],
            "family": "Nimzo-Indian Defense",
            "volume": "E",
            "variation": "Classical Variation, Noa Variation, Main Line"
        }
    },
    "meta": {
        "timestamp": "2026-05-31T09:34:54.986Z",
        "request_id": "83348a25-604e-42a4-b5f1-b8383f8d219c"
    },
    "status": "ok",
    "message": "Random opening",
    "success": true
}
```

#### `GET /v1/search` — Search & filter openings

**Parameters:**
- `q` (query, optional, string) — Search by opening name Example: `sicilian`
- `eco` (query, optional, string) — Exact ECO code, e.g. B20
- `volume` (query, optional, string) — ECO volume A, B, C, D or E
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chessopenings-api/v1/search?q=sicilian&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "total": 344,
        "offset": 0,
        "filters": {
            "q": "sicilian",
            "eco": null,
            "volume": null
        },
        "results": [
            {
                "eco": "B20",
                "pgn": "1. e4 c5",
                "ply": 2,
                "name": "Sicilian Defense",
                "moves": [
                    "e4",
                    "c5"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": null
            },
            {
                "eco": "B20",
                "pgn": "1. e4 c5 2. Qg4",
                "ply": 3,
                "name": "Sicilian Defense: Amazon Attack",
                "moves": [
                    "e4",
                    "c5",
                    "Qg4"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": "Amazon Attack"
            },
            {
                "eco": "B20",
                "pgn": "1. e4 c5 2. Bc4",
                "ply": 3,
                "name": "Sicilian Defense: Bowdler Attack",
                "moves": [
                    "e4",
                    "c5",
                    "Bc4"
                ],
                "family": "Sicilian Defense",
                "volume": "B",
                "variation": "Bowdler Attack"
            },
            {
             
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & ECO volumes

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

**Response:**
```json
{
    "data": {
        "note": "The Encyclopaedia of Chess Openings (ECO). Search by name/eco/volume, list by ECO code, identify an opening from a move sequence (/v1/identify?moves=1. e4 c5), or get a random opening.",
        "total": 3161,
        "fields": [
            "eco",
            "name",
            "family",
            "variation",
            "pgn",
            "moves",
            "ply",
            "volume"
        ],
        "source": "lichess-org/chess-openings (ECO)",
        "volumes": {
            "A": "Flank openings",
            "B": "Semi-Open Games (except the French)",
            "C": "Open Games & the French",
            "D": "Closed & Semi-Closed Games",
            "E": "Indian Defences"
        },
        "by_volume": {
            "A": 672,
            "B": 674,
            "C": 1089,
            "D": 458,
            "E": 268
        },
        "eco_codes": 464
    },
    "meta": {
        "timestamp": "2026-05-31T09:34:55.117Z",
        "request_id": "7cf52043-eb6d-4e49-8e99-457e23574854"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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