Opening Match API

Real-time chess opening identification and transition analysis based on move sequences.

GET

/api/openings/match

Identifies chess openings and transitions that match the provided move sequence.

Query Parameters

moveHistory

string (required) - JSON string array of moves

Example Request

// Example move sequence: 1.e4 e5 2.Nf3 Nc6 3.Bb5
const moves = ["e4", "e5", "Nf3", "Nc6", "Bb5"];
const response = await fetch(`/api/openings/match?moveHistory=${encodeURIComponent(JSON.stringify(moves))}`);

Success Response

{
  "exactMatches": true,
  "count": 3,
  "openings": [
    {
      "id": "string",
      "fen": "string",
      "eco": "C60",
      "moves": "1. e4 e5 2. Nf3 Nc6 3. Bb5",
      "name": "Ruy Lopez",
      "src": "string",
      "isEcoRoot": true,
      "aliases": [
        {
          "source": "string",
          "value": "Spanish Opening"
        }
      ]
    }
  ],
  "transitions": [
    {
      "id": "string",
      "fromFen": "string",
      "toFen": "string",
      "fromSrc": "string",
      "toSrc": "string",
      "fromOpening": {
        "id": "string",
        "fen": "string",
        "eco": "C60",
        "name": "Ruy Lopez",
        "moves": "string"
      },
      "toOpening": {
        "id": "string",
        "fen": "string",
        "eco": "C65",
        "name": "Ruy Lopez, Berlin Defense",
        "moves": "string"
      }
    }
  ],
  "searchInfo": {
    "normalizedMoves": "1. e4 e5 2. Nf3 Nc6 3. Bb5",
    "movesCount": 5,
    "moves": ["e4", "e5", "Nf3", "Nc6", "Bb5"]
  }
}

Error Responses

400 Bad Request - Missing Parameter

{
  "error": "El parámetro moveHistory es requerido"
}

400 Bad Request - Invalid Format

{
  "error": "Formato inválido para moveHistory. Debe ser un array JSON"
}

Move Format Specification

Input Format

Type: JSON string array
Example: ["e4", "e5", "Nf3", "Nc6", "Bb5"]
Requirements: Standard algebraic notation, alternating white and black moves

Normalized Format

Input: ["e4", "e5", "Nf3", "Nc6", "Bb5"]
Output: "1. e4 e5 2. Nf3 Nc6 3. Bb5"

Search Logic

Opening Matching

Prefix Match: Openings where move sequence exactly matches from start
Containment Match: Openings that contain move sequence at any point
Sorting Priority: ECO root openings first, then by ECO code, then move length

Transition Matching

Move sequence matches either fromSrc or toSrc fields
Provides context for opening changes and variations