Analysis

Analysis API

Access the Lichess cloud evaluations database.

Namespace: LichessSharp.Api.Contracts Access: client.Analysis

---

Methods

GetCloudEvaluationAsync

Get cloud evaluation for a position from the Lichess analysis database.

Task<CloudEvaluation?> GetCloudEvaluationAsync(
    string fen,
    int? multiPv = null,
    string? variant = null,
    CancellationToken cancellationToken = default)

Parameters:

Name	Type	Description
fen	string	FEN of the position to evaluate
multiPv	int?	Number of principal variations (1-5)
variant	string?	Chess variant (default: standard)

Returns: CloudEvaluation? - The cloud evaluation, or null if the position is not in the database.

Example:

using var client = new LichessClient();

// Get evaluation for the starting position
var startingPos = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
var eval = await client.Analysis.GetCloudEvaluationAsync(startingPos);

if (eval != null)
{
    Console.WriteLine($"Position: {eval.Fen}");
    Console.WriteLine($"Depth: {eval.Depth}");
    Console.WriteLine($"Nodes: {eval.Knodes}k");

    foreach (var pv in eval.Pvs ?? [])
    {
        if (pv.Cp.HasValue)
        {
            Console.WriteLine($"  Eval: {pv.Cp / 100.0:+0.00;-0.00} - {pv.Moves}");
        }
        else if (pv.Mate.HasValue)
        {
            Console.WriteLine($"  Mate in {pv.Mate} - {pv.Moves}");
        }
    }
}
else
{
    Console.WriteLine("Position not found in cloud database");
}

---

Multi-PV Analysis

Request multiple principal variations:

using var client = new LichessClient();

var fen = "r1bqkb1r/pppp1ppp/2n2n2/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 4 4";

// Get top 3 lines
var eval = await client.Analysis.GetCloudEvaluationAsync(fen, multiPv: 3);

if (eval != null)
{
    Console.WriteLine($"Top {eval.Pvs?.Count ?? 0} moves:");
    var rank = 1;
    foreach (var pv in eval.Pvs ?? [])
    {
        var evalStr = pv.Cp.HasValue
            ? $"{pv.Cp / 100.0:+0.00;-0.00}"
            : $"M{pv.Mate}";
        var firstMove = pv.Moves.Split(' ').FirstOrDefault();
        Console.WriteLine($"  {rank}. {firstMove} ({evalStr})");
        rank++;
    }
}

---

Chess Variants

Query evaluations for chess variants:

using var client = new LichessClient();

// Chess960 position
var chess960Fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
var chess960Eval = await client.Analysis.GetCloudEvaluationAsync(chess960Fen, variant: "chess960");

// Antichess position
var antichessFen = "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1";
var antichessEval = await client.Analysis.GetCloudEvaluationAsync(antichessFen, variant: "antichess");

Supported variants:

• standard (default)
• chess960
• antichess
• atomic
• horde
• kingOfTheHill
• racingKings
• threeCheck
• crazyhouse

---

Response Types

CloudEvaluation

Property	Type	Description
Fen	string	The FEN position
Knodes	long	Number of nodes searched (in thousands)
Depth	int	Search depth
Pvs	IReadOnlyList<PrincipalVariation>?	Principal variations

PrincipalVariation

Property	Type	Description
Moves	string	Moves in UCI notation (space-separated)
Cp	int?	Centipawn evaluation (100 cp = 1 pawn)
Mate	int?	Mate in N moves (positive = white mates)

---

Notes

• The cloud database contains evaluations from Lichess users' analyses
• Not all positions are available - the method returns null for unknown positions
• Evaluations come from Stockfish analysis performed by users
• Higher depth and more nodes generally indicate more reliable evaluations

---

See Also

• Opening Explorer API - Opening statistics
• Tablebase API - Endgame tablebases
• Games API - Export games with analysis