# 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.

```csharp
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:**

```csharp
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:

```csharp
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:

```csharp
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](OpeningExplorer.md) - Opening statistics
- [Tablebase API](Tablebase.md) - Endgame tablebases
- [Games API](Games.md) - Export games with analysis