OpeningExplorer

Opening Explorer API

Lookup positions from the Lichess opening explorer databases.

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

---

Databases

The Opening Explorer provides access to three databases:

Database	Description
Masters	Over-the-board games from titled players (2200+ FIDE)
Lichess	All rated games played on Lichess
Player	Games of a specific Lichess player

---

Methods

GetMastersAsync

Get opening explorer data from the masters database.

Task<ExplorerResult> GetMastersAsync(
    string fen,
    ExplorerOptions? options = null,
    CancellationToken cancellationToken = default)

Example:

using var client = new LichessClient();

// Starting position
var fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";

var result = await client.OpeningExplorer.GetMastersAsync(fen, new ExplorerOptions
{
    Moves = 10,
    TopGames = 5,
    Since = 2000,
    Until = 2024
});

Console.WriteLine($"Opening: {result.Opening?.Name} ({result.Opening?.Eco})");
Console.WriteLine($"Total games: {result.White + result.Draws + result.Black}");
Console.WriteLine($"White wins: {result.White}, Draws: {result.Draws}, Black wins: {result.Black}");

Console.WriteLine("\nPopular moves:");
foreach (var move in result.Moves ?? [])
{
    var total = move.White + move.Draws + move.Black;
    var whitePercent = total > 0 ? (double)move.White / total * 100 : 0;
    Console.WriteLine($"  {move.San}: {total} games, {whitePercent:F1}% white wins");
}

Console.WriteLine("\nTop games:");
foreach (var game in result.TopGames ?? [])
{
    Console.WriteLine($"  {game.Id} ({game.Year}) - Winner: {game.Winner ?? "draw"}");
}

---

GetLichessAsync

Get opening explorer data from the Lichess database.

Task<ExplorerResult> GetLichessAsync(
    string fen,
    ExplorerOptions? options = null,
    CancellationToken cancellationToken = default)

Example:

using var client = new LichessClient();

var fen = "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1";

var result = await client.OpeningExplorer.GetLichessAsync(fen, new ExplorerOptions
{
    Speeds = new[] { "blitz", "rapid" },
    Ratings = new[] { 2000, 2200, 2500 },
    Moves = 15,
    RecentGames = 3
});

Console.WriteLine($"Opening: {result.Opening?.Name}");
Console.WriteLine($"Filtered games: {result.White + result.Draws + result.Black}");

Console.WriteLine("\nMoves by popularity:");
foreach (var move in result.Moves?.Take(5) ?? [])
{
    var total = move.White + move.Draws + move.Black;
    Console.WriteLine($"  {move.San} ({move.Uci}): {total} games, avg rating {move.AverageRating}");
}

---

GetPlayerAsync

Get opening explorer data for a specific Lichess player.

Task<ExplorerResult> GetPlayerAsync(
    string fen,
    string player,
    ExplorerOptions? options = null,
    CancellationToken cancellationToken = default)

Example:

using var client = new LichessClient();

var fen = "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1";

// Get DrNykterstein's responses to 1.e4 as Black
var result = await client.OpeningExplorer.GetPlayerAsync(fen, "DrNykterstein",
    new ExplorerOptions
    {
        Color = "black",
        Speeds = new[] { "blitz", "bullet" },
        RecentGames = 5
    });

Console.WriteLine($"DrNykterstein's responses to 1.e4:");
Console.WriteLine($"Games as black: {result.White + result.Draws + result.Black}");

foreach (var move in result.Moves ?? [])
{
    var total = move.White + move.Draws + move.Black;
    var winRate = total > 0 ? (double)move.Black / total * 100 : 0;
    Console.WriteLine($"  {move.San}: {total} games, {winRate:F1}% win rate");
}

Console.WriteLine("\nRecent games:");
foreach (var game in result.RecentGames ?? [])
{
    Console.WriteLine($"  lichess.org/{game.Id} ({game.Month})");
}

---

GetMasterGamePgnAsync

Get a specific game from the masters database as PGN.

Task<string> GetMasterGamePgnAsync(
    string gameId,
    CancellationToken cancellationToken = default)

Example:

using var client = new LichessClient();

// Get a famous game from the masters database
var pgn = await client.OpeningExplorer.GetMasterGamePgnAsync("aAbqW4EY");
Console.WriteLine(pgn);

// Save to file
await File.WriteAllTextAsync("master_game.pgn", pgn);

---

Options

ExplorerOptions

Property	Type	Description	Databases
Moves	int?	Number of moves to return	All
TopGames	int?	Number of top games to return	All
RecentGames	int?	Number of recent games to return	All
Since	int?	Games from this year or later	Masters
Until	int?	Games from this year or earlier	Masters
Variant	string?	Chess variant	Lichess, Player
Speeds	string[]?	Time controls to include	Lichess, Player
Ratings	int[]?	Rating ranges to include	Lichess, Player
SinceMonth	string?	Games from this month or later (YYYY-MM)	Lichess, Player
UntilMonth	string?	Games from this month or earlier (YYYY-MM)	Lichess, Player
Color	string?	Player's color ("white" or "black")	Player (required)

Speeds: "ultraBullet", "bullet", "blitz", "rapid", "classical", "correspondence"

Ratings: 0, 1000, 1200, 1400, 1600, 1800, 2000, 2200, 2500

---

Response Types

ExplorerResult

Property	Type	Description
White	long	White wins
Draws	long	Draws
Black	long	Black wins
Moves	IReadOnlyList<ExplorerMove>?	Available moves
TopGames	IReadOnlyList<ExplorerGame>?	Top games
RecentGames	IReadOnlyList<ExplorerGame>?	Recent games
Opening	ExplorerOpening?	Opening information

ExplorerMove

Property	Type	Description
Uci	string	Move in UCI notation
San	string	Move in SAN notation
White	long	White wins after this move
Draws	long	Draws after this move
Black	long	Black wins after this move
AverageRating	int?	Average opponent rating

ExplorerGame

Property	Type	Description
Id	string	Game ID
Winner	string?	"white", "black", or null (draw)
Year	int?	Year played
Month	string?	Month played (YYYY-MM)

ExplorerOpening

Property	Type	Description
Eco	string?	ECO code (e.g., "B20")
Name	string?	Opening name

---

See Also

• Analysis API - Cloud evaluations
• Tablebase API - Endgame tablebases
• Games API - Export full games