Chess Game Analysis API

Send a PGN. Get move-by-move classification, accuracy scores, turning points, tactical themes, and a personalized study plan. The automated chess analysis API that explains why, not just what.

Get Started View Documentation

Input · PGN

[Event "Casual Game"]
[White "Player1"]
[Black "Player2"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nc6
3. Bb5 a6 4. Ba4 Nf6
5. O-O Be7 6. Re1 b5
7. Bb3 d6 8. c3 O-O
... 20 more moves

→

Output · JSON

{
  "game_summary": { ... opening, accuracy, result },
  "overview": { ... phase summaries, narrative },
  "turning_points": [ ... 5-7 key moments ],
  "white_mistakes": [ ... with better moves ],
  "study_plan": { ... strengths, weaknesses, drills },
  "response": "Your biggest mistake was Na5..."
}

Response Breakdown

What the chess game analysis API returns

One API call. A complete game review with coaching your users can learn from.

Overview & Narrative

{
  "overview": {
    "summary_sentence":
      "White's initiative...",
    "overview_bullets": [...],
    "white_opening": "Solid",
    "black_middlegame": "Weak"
  }
}

LLM-generated narrative summary plus phase-by-phase assessment for both sides (opening, middlegame, endgame).

Game Summary

{
  "game_summary": {
    "result": "1-0",
    "opening": "Ruy Lopez, Closed",
    "eco": "C84",
    "total_moves": 28,
    "white_accuracy": 87.3,
    "black_accuracy": 73.1
  }
}

Opening identification, ECO code, and accuracy percentage for both players.

Move Classification

{
  "classification": "mistake",
  "move": "Na5",
  "evaluation_after": -85
}

Eight classification levels: brilliant, best, excellent, good, book, inaccuracy, mistake, blunder. Every move categorized.

Coaching Response

{
  "response": "Your biggest
    mistake was 18...Na5,
    which allowed White to
    gain space with d5."
}

Natural language coaching focused on the player's color. Explains what went wrong and how to improve.

Turning Points

{
  "turning_points": [{
    "ply": 18,
    "move": "Na5",
    "phase": "middlegame",
    "swing_pp": 15.2,
    "explanation": "This shifted..."
  }]
}

5-7 strategically important moments with phase-diverse selection. Each includes the win-probability swing and LLM explanation.

Mistakes by Side

{
  "white_mistakes": [{
    "ply": 15,
    "move": "Na5",
    "swing_pp": 12.3,
    "move_category": "mistake",
    "better_move": "c4c5",
    "why": "Knight is misplaced..."
  }]
}

Mistakes and blunders separated by side, with win-probability swing and the better alternative for each.

Tactical Themes

{
  "tactical_themes": {
    "themes": {
      "fork": { "white": 2, "missed": 1 },
      "pin": { "black": 1 }
    },
    "total_motifs": 4
  }
}

Game-level tactical summary: forks, pins, skewers, sacrifices — counted per side with missed motifs tracked separately.

Study Plan

{
  "study_plan": {
    "for_color": "black",
    "strengths": ["No blunders"],
    "weaknesses": ["Calculation"],
    "opening_work": "Study the...",
    "tactics_work": "You missed...",
    "strategic_work": "Your knight..."
  }
}

A personalized study plan derived from the game: strengths, weaknesses, and specific drills for openings, tactics, strategy, and endgames.

Integration

Integrate chess game analysis in five lines

Python

import requests

response = requests.post("https://api.chessvia.ai/analyze_game",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 ...",
        "player_color": "black",
        "skill_level": "intermediate"
    }
)

data = response.json()
print(data["game_summary"]["black_accuracy"])  # 73.1
print(data["response"])                         # Coaching text
print(data["study_plan"]["weaknesses"])          # Areas to improve

JavaScript

const response = await fetch("https://api.chessvia.ai/analyze_game", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    pgn: "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 ...",
    player_color: "black",
    skill_level: "intermediate"
  })
});

const data = await response.json();
console.log(data.game_summary.black_accuracy);  // 73.1
console.log(data.turning_points);                // Key moments

cURL

curl -X POST https://api.chessvia.ai/analyze_game \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pgn": "1. e4 e5 2. Nf3 Nc6 ...", "player_color": "black"}'

Accuracy

Chess accuracy scoring developers can trust

Every game gets an accuracy percentage for both players. Comparable to the scores you see on major chess platforms — exposed through an API.

White

87.3%Excellent

Black

73.1%Good

95-100% Perfect85-95% Excellent75-85% Good60-75% Fair<60% Needs work

Classification

Eight levels of move quality

Click any classification to see an example. Every move in the game gets categorized, giving your users the granularity they need.

Parameters

Control what you get back

Toggle player focus to see how coaching changes perspective.

White's coaching: Strong game overall with 87.3% accuracy. Your key moment was 10. Nxb5 — you correctly identified the tactical opportunity to win material. Focus area: the endgame technique after move 20 could be more precise.

Player focus

player_color: "white" | "black"

Coaching explains their moves and highlights their mistakes.

Motif detection

detect_motifs: true | false

Adds named tactical themes per move.

Detail levels

brief | standard | detailed

Brief for notifications. Standard for reviews. Detailed for coaching.

Move scope

include_all_moves: true | false

Analyze all moves or just errors. Cap with max_moves_analyzed.

Use Cases

What you can build

Post-Game Review

Users finish a game, tap "Review," and see move-by-move analysis with accuracy and coaching — powered by one API call.

Student Progress

Track accuracy trends across games. Identify recurring mistake types. Give chess academies data-driven coaching.

Live Commentary

Auto-annotate games during broadcasts. Show viewers which moves were brilliant, which were mistakes, and why.

Get Started

Ready to Integrate?

Usage-based pricing with no fixed commitments. Reach out and we'll get you set up with an API key.

Get in touch

Tell us about your project and we'll set you up with an API key.

FAQ

Questions

What format does the chess game analysis API accept?

Standard PGN (Portable Game Notation). Include moves at minimum. Headers like [Event], [Date], [Result] are optional but improve analysis quality.

How fast is automated game analysis via the API?

Response time depends on game length and analysis depth. Short games return in under a minute; longer games may take slightly more. Results include move classification, accuracy scores, and coaching in a single call.

Can I analyze partial games or games in progress?

Yes. Send any number of moves (minimum 2). Useful for live broadcasting or analyzing games still in progress.

Can I get chess analysis for both players in one API call?

Yes. Omit player_color and the response includes accuracy and move analysis for both sides. Set player_color to focus coaching on one player.

What makes this different from other chess analysis APIs?

Most chess APIs return raw engine scores. Chessvia returns structured coaching: study plans, turning points, mistake explanations, and tactical themes — everything your users need to improve, not just numbers.

Do you detect openings and tactical patterns?

Yes. Every game gets an opening name, ECO code, and tactical theme detection across forks, pins, skewers, discoveries, and more. Missed tactics are tracked per side.

Ready to add automated chess game analysis?

One API call. Move-by-move analysis, accuracy scores, study plans, and coaching your users can learn from.

Get in touch

Tell us about your project and we'll set you up with an API key.

Need position-level detail? See Position Analysis API · Try game analysis in your browser

Chess Game Analysis API

Send a PGN. Get move-by-move classification, accuracy scores, turning points, tactical themes, and a personalized study plan. The automated chess analysis API that explains why, not just what.

Get Started View Documentation

Input · PGN

[Event "Casual Game"]
[White "Player1"]
[Black "Player2"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nc6
3. Bb5 a6 4. Ba4 Nf6
5. O-O Be7 6. Re1 b5
7. Bb3 d6 8. c3 O-O
... 20 more moves

→

Output · JSON

{
  "game_summary": { ... opening, accuracy, result },
  "overview": { ... phase summaries, narrative },
  "turning_points": [ ... 5-7 key moments ],
  "white_mistakes": [ ... with better moves ],
  "study_plan": { ... strengths, weaknesses, drills },
  "response": "Your biggest mistake was Na5..."
}

Response Breakdown

What the chess game analysis API returns

One API call. A complete game review with coaching your users can learn from.

Overview & Narrative

{
  "overview": {
    "summary_sentence":
      "White's initiative...",
    "overview_bullets": [...],
    "white_opening": "Solid",
    "black_middlegame": "Weak"
  }
}

LLM-generated narrative summary plus phase-by-phase assessment for both sides (opening, middlegame, endgame).

Game Summary

{
  "game_summary": {
    "result": "1-0",
    "opening": "Ruy Lopez, Closed",
    "eco": "C84",
    "total_moves": 28,
    "white_accuracy": 87.3,
    "black_accuracy": 73.1
  }
}

Opening identification, ECO code, and accuracy percentage for both players.

Move Classification

{
  "classification": "mistake",
  "move": "Na5",
  "evaluation_after": -85
}

Eight classification levels: brilliant, best, excellent, good, book, inaccuracy, mistake, blunder. Every move categorized.

Coaching Response

{
  "response": "Your biggest
    mistake was 18...Na5,
    which allowed White to
    gain space with d5."
}

Natural language coaching focused on the player's color. Explains what went wrong and how to improve.

Turning Points

{
  "turning_points": [{
    "ply": 18,
    "move": "Na5",
    "phase": "middlegame",
    "swing_pp": 15.2,
    "explanation": "This shifted..."
  }]
}

5-7 strategically important moments with phase-diverse selection. Each includes the win-probability swing and LLM explanation.

Mistakes by Side

{
  "white_mistakes": [{
    "ply": 15,
    "move": "Na5",
    "swing_pp": 12.3,
    "move_category": "mistake",
    "better_move": "c4c5",
    "why": "Knight is misplaced..."
  }]
}

Mistakes and blunders separated by side, with win-probability swing and the better alternative for each.

Tactical Themes

{
  "tactical_themes": {
    "themes": {
      "fork": { "white": 2, "missed": 1 },
      "pin": { "black": 1 }
    },
    "total_motifs": 4
  }
}

Game-level tactical summary: forks, pins, skewers, sacrifices — counted per side with missed motifs tracked separately.

Study Plan

{
  "study_plan": {
    "for_color": "black",
    "strengths": ["No blunders"],
    "weaknesses": ["Calculation"],
    "opening_work": "Study the...",
    "tactics_work": "You missed...",
    "strategic_work": "Your knight..."
  }
}

A personalized study plan derived from the game: strengths, weaknesses, and specific drills for openings, tactics, strategy, and endgames.

Integration

Integrate chess game analysis in five lines

Python

import requests

response = requests.post("https://api.chessvia.ai/analyze_game",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 ...",
        "player_color": "black",
        "skill_level": "intermediate"
    }
)

data = response.json()
print(data["game_summary"]["black_accuracy"])  # 73.1
print(data["response"])                         # Coaching text
print(data["study_plan"]["weaknesses"])          # Areas to improve

JavaScript

const response = await fetch("https://api.chessvia.ai/analyze_game", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    pgn: "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 ...",
    player_color: "black",
    skill_level: "intermediate"
  })
});

const data = await response.json();
console.log(data.game_summary.black_accuracy);  // 73.1
console.log(data.turning_points);                // Key moments

cURL

curl -X POST https://api.chessvia.ai/analyze_game \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pgn": "1. e4 e5 2. Nf3 Nc6 ...", "player_color": "black"}'

Accuracy

Chess accuracy scoring developers can trust

Every game gets an accuracy percentage for both players. Comparable to the scores you see on major chess platforms — exposed through an API.

White

87.3%Excellent

Black

73.1%Good

95-100% Perfect85-95% Excellent75-85% Good60-75% Fair<60% Needs work

Classification

Eight levels of move quality

Click any classification to see an example. Every move in the game gets categorized, giving your users the granularity they need.

Parameters

Control what you get back

Toggle player focus to see how coaching changes perspective.

Player focus

player_color: "white" | "black"

Coaching explains their moves and highlights their mistakes.

Motif detection

detect_motifs: true | false

Adds named tactical themes per move.

Detail levels

brief | standard | detailed

Brief for notifications. Standard for reviews. Detailed for coaching.

Move scope

include_all_moves: true | false

Analyze all moves or just errors. Cap with max_moves_analyzed.

Use Cases

What you can build

Post-Game Review

Users finish a game, tap "Review," and see move-by-move analysis with accuracy and coaching — powered by one API call.

Student Progress

Track accuracy trends across games. Identify recurring mistake types. Give chess academies data-driven coaching.

Live Commentary

Auto-annotate games during broadcasts. Show viewers which moves were brilliant, which were mistakes, and why.

Get Started

Ready to Integrate?

Usage-based pricing with no fixed commitments. Reach out and we'll get you set up with an API key.

Get in touch

Tell us about your project and we'll set you up with an API key.

FAQ

Questions

What format does the chess game analysis API accept?

Standard PGN (Portable Game Notation). Include moves at minimum. Headers like [Event], [Date], [Result] are optional but improve analysis quality.

How fast is automated game analysis via the API?

Can I analyze partial games or games in progress?

Yes. Send any number of moves (minimum 2). Useful for live broadcasting or analyzing games still in progress.

Can I get chess analysis for both players in one API call?

Yes. Omit player_color and the response includes accuracy and move analysis for both sides. Set player_color to focus coaching on one player.

What makes this different from other chess analysis APIs?

Do you detect openings and tactical patterns?

Yes. Every game gets an opening name, ECO code, and tactical theme detection across forks, pins, skewers, discoveries, and more. Missed tactics are tracked per side.

Ready to add automated chess game analysis?

One API call. Move-by-move analysis, accuracy scores, study plans, and coaching your users can learn from.

Get in touch

Tell us about your project and we'll set you up with an API key.

Need position-level detail? See Position Analysis API · Try game analysis in your browser