Back to API Reference

Openings API

Search and browse the chess openings database with advanced filtering and sorting options.

GET
/api/openings

Retrieves a paginated list of chess openings with extensive filtering and sorting options.

Query Parameters

page
number (optional, default: 1)
limit
number (optional, default: 20)
search
string (optional)
eco
string (optional)
sort
popular, favorites, recent, name, eco (optional, default: popular)
favoritesOnly
boolean (optional, default: false)
userId
string (optional, for personalized data)

Example Requests

// Get popular openings with pagination
const response = await fetch('/api/openings?page=1&limit=20&sort=popular');

// Search for Sicilian Defense variations
const response = await fetch('/api/openings?search=sicilian&sort=name');

// Filter by ECO code and show user favorites
const response = await fetch('/api/openings?eco=C60&favoritesOnly=true&userId=user123');

// Get all openings sorted by name
const response = await fetch('/api/openings?sort=name&limit=50');

Success Response

{
  "openings": [
    {
      "id": "string",
      "fen": "string",
      "name": "Ruy Lopez",
      "eco": "C60",
      "moves": "1. e4 e5 2. Nf3 Nc6 3. Bb5",
      "src": "string",
      "scid": "string",
      "isEcoRoot": true,
      "aliases": [
        {
          "id": "string",
          "value": "Spanish Opening",
          "source": "string",
          "openingId": "string"
        }
      ],
      "totalVisits": 150,
      "totalFavorites": 25,
      "totalPracticeSessions": 75,
      "isFavorite": true,
      "userVisitCount": 5
    }
  ],
  "ecoOptions": ["A00", "A01", "B20", "C60", "D00"],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasMore": true
  }
}

Error Response

500 Internal Server Error
{
  "error": "Internal server error"
}

Search & Filtering

Search Functionality

  • Opening Name: Case-insensitive partial matching
  • ECO Code: Exact or partial ECO code matching
  • Move Sequences: Partial move sequence matching
  • Aliases: Alternative opening names

Filtering Options

  • ECO Filtering: Filter by exact ECO code match
  • Favorites Filter: Only show user's favorite openings
  • User-Specific Data: Include personalized data when userId provided

Sorting Options

popular
Most visited openings (descending by totalVisits)
favorites
Most favorited openings (descending by totalFavorites)
recent
Default sorting (ascending by eco, then name)
name
Alphabetical by opening name (ascending by name)
eco
By ECO classification code (ascending by eco, then name)