Chess Opponent Analyzer

Fetch a chess player's full game history from Lichess and Chess.com, analyze their opening repertoire, and get an actionable preparation report before your next game.

---

What Does the Chess Opponent Analyzer Do?

The Chess Opponent Analyzer fetches a player's game history from Lichess (with Chess.com support coming in Phase 2) and produces a detailed opening repertoire report. You get win rates per opening, a full move-tree, and signals for recent preparation changes -- everything a coach or player needs the night before a tournament game.

Core capabilities:

• 📥 Fetches up to 1500 games from Lichess via the official NDJSON API
• ♟️ Builds a per-color opening tree (up to 30 plies deep) with win/draw/loss stats at every node
• 📊 Ranks top openings by ECO code with frequency and win rate
• 📈 Detects recent trends: openings the opponent started playing more or less in the last 30 days
• 🚨 Flags surprise openings: lines played recently but historically rare (< 3% of games)
• 🔁 Surfaces rare repeated lines (< 5% frequency, 3+ games) -- signature sidelines worth preparing
• ⏱️ Splits performance by time control: classical, rapid, blitz, bullet
• 📄 Optionally exports all games as a PGN file for Chessbase or Stockfish analysis

---

What Data Does the Chess Opponent Analyzer Return?

Opening analysis	Performance data	Metadata
♟️ ECO code and opening name	📊 Win / draw / loss counts	🗓️ Date range analyzed
🌳 Full opening tree (configurable depth)	📈 Win rate, draw rate, loss rate	🕐 Time of analysis
🎯 First-move frequency (White)	🕐 Performance by time control	🎮 Source platform (Lichess)
🔄 Black responses vs 1.e4 / 1.d4 / 1.c4 / 1.Nf3	📉 Recent 30-day trends	🆔 Game IDs and URLs
🚨 Surprise openings (new preparation signals)	🔁 Rare repeated sidelines	📄 PGN export link

---

Can I Use the Chess Opponent Analyzer to Study Magnus Carlsen, Hikaru Nakamura, or Any Other Lichess Player?

Yes. The Chess Opponent Analyzer works for any public Lichess profile. Enter the Lichess username (for example, DrNykterstein for Magnus Carlsen or nihalsarin for Nihal Sarin) and the actor fetches their full game history. All publicly visible games are available without authentication -- adding a Lichess API token only raises rate limits for high-volume use.

---

How Does the Chess Opponent Analyzer Work?

The Process

1. You provide a Lichess username and optional filters (date range, time control, rated/casual, color, minimum opponent rating)
2. The actor fetches up to 1,500 games from the Lichess streaming API in NDJSON format
3. Each game is normalized: result, ECO code, opening name, player color, opponent rating, and move list are all extracted
4. The move list is parsed into SAN tokens (annotations and move numbers stripped)
5. An opening tree is built by traversing moves up to your chosen depth and counting wins/draws/losses at every node
6. Statistical layers are added: ECO rankings, first-move frequencies, Black response maps, trend analysis, surprise detection, and rare-line surfacing
7. The full analysis is pushed as a single JSON record to the Apify dataset
8. If PGN export is enabled, all games are saved as a .pgn file to the key-value store

Think of it as running your own personal opening preparation team, except it processes 500 games in under 30 seconds.

---

Why Use the Chess Opponent Analyzer?

Feature	Manual research	Chess Opponent Analyzer
Time to analyze 500 games	Several hours	Under 60 seconds
Opening tree depth	Limited by patience	Up to 30 plies (configurable)
Surprise detection	Hard to spot manually	Automatic: flags openings with < 3% historical rate
Trend analysis	Requires date-based sorting	Built-in 30-day vs 60-day comparison
Export for engine analysis	Manual PGN copy-paste	One-click PGN download
Multi-time-control split	Separate sessions	Automatic breakdown per time control
Structured output for pipelines	Not possible	Full JSON via Apify dataset API

---

What Can You Do With Opening Analysis Data?

Tournament preparation

Import the opening tree JSON into your preparation workflow. The tree structure maps directly to standard repertoire formats -- you can see exactly what your opponent plays after 1.e4 e5 2.Nf3 Nc6 and how their win rate changes move by move. Filter to classical or rapid only when preparing for a classical event.

Coaching and training

Coaches can run the actor for every upcoming opponent of a student and store all results in a shared Apify dataset. Use the datasetId parameter to append all players into a single dataset for easy comparison. The structured JSON output integrates with any custom dashboard.

Opening research

The recentTrends and surprises arrays answer the key preparation question: "Has this player changed their opening approach lately?" An increasing trend in a line you haven't prepared is a concrete signal. A surprise opening with 3 recent games but near-zero historical rate means they may have specifically prepared it.

PGN integration

Enable exportPgn: true to get a direct download URL for a PGN file containing all fetched games. Load it into Chessbase, Stockfish (via Arena or Lichess Study), or any PGN viewer for deeper engine-assisted analysis.

Scheduling

Run weekly in the month before a major tournament to catch preparation changes early. Run daily for rapid or blitz events where opponents may have evolved their openings recently. Use the Apify scheduler or connect via the API to trigger runs automatically.

---

How to Use the Chess Opponent Analyzer

1. Go to the Chess Opponent Analyzer page on the Apify Store and click Try for free
2. In the Input tab, enter the Lichess username of the player you want to analyze
3. Set your filters: date range, time controls, rated/casual, minimum opponent rating
4. Optionally increase Max Games (up to 1,500) for deeper statistical analysis
5. Optionally enable Export PGN if you want to load games into Chessbase or Stockfish
6. Click Start and wait for the run to complete (usually 10--60 seconds)
7. Open the Output tab to see the full analysis record
8. Download as JSON, CSV, or use the Apify API to pull results into your own tools

Recommendation: start with timeControls: ["rapid"] and maxGames: 200. Rapid games reflect a player's real preparation better than blitz and contain more opening theory than bullet.

---

How Much Does the Chess Opponent Analyzer Cost?

The Chess Opponent Analyzer uses the pay-per-event model. A typical run analyzing 500 rapid games costs less than $0.05 in compute units. The main cost driver is the number of games fetched -- more games means more parsing and analysis.

Cost optimization tips:

• Use maxGames: 200-500 for most preparation needs -- diminishing returns above 500 for active players
• Set dateFrom to limit to the last 12--18 months -- older games may not reflect current preparation
• Set minOpponentRating (e.g. 2300+) to filter out low-quality games and focus the analysis
• Add a lichessApiToken to avoid rate-limit retries -- reduces runtime, not cost

---

Input

The Chess Opponent Analyzer accepts the following input parameters:

Parameter	Type	Default	Description
lichessUsername	string	--	Lichess username to analyze (e.g. DrNykterstein)
chesscomUsername	string	--	Chess.com username (Phase 2, not yet active)
platform	string	lichess	Source platform: lichess, chesscom, or all
dateFrom	string	--	Start date in ISO format: 2024-01-01
dateTo	string	--	End date in ISO format: 2024-12-31
timeControls	array	["all"]	One or more of: classical, rapid, blitz, bullet, all
rated	string	rated	rated, casual, or all
color	string	both	white, black, or both
minOpponentRating	integer	0	Only include games vs opponents at or above this rating
maxGames	integer	500	Maximum games to fetch (up to 1,500)
openingTreeDepth	integer	12	Plies to include in opening tree (4--30)
exportPgn	boolean	false	Save all games as a PGN file to key-value store
lichessApiToken	string	--	Optional Lichess token to increase rate limits
datasetId	string	--	Append results to an existing Apify dataset
runId	string	--	Associate results with a pipeline run

Example input -- basic tournament preparation:

{
    "lichessUsername": "nihalsarin",
    "timeControls": ["rapid", "classical"],
    "dateFrom": "2024-01-01",
    "rated": "rated",
    "minOpponentRating": 2500,
    "maxGames": 500
}

Example input -- deep blitz analysis with PGN export:

{
    "lichessUsername": "DrNykterstein",
    "timeControls": ["blitz"],
    "maxGames": 1000,
    "openingTreeDepth": 20,
    "exportPgn": true
}

---

Output

The Chess Opponent Analyzer produces a single JSON record per run pushed to the Apify dataset.

Example output structure:

{
    "player": "nihalsarin",
    "gamesAnalyzed": 312,
    "dateRange": { "from": "2024-01-15", "to": "2024-12-20" },
    "sources": { "lichess": 312 },
    "summary": {
        "games": 312,
        "wins": 180,
        "draws": 100,
        "losses": 32,
        "winRate": 0.577,
        "drawRate": 0.321,
        "lossRate": 0.103
    },
    "white": {
        "games": 156,
        "summary": { "wins": 95, "draws": 50, "losses": 11, "winRate": 0.609 },
        "firstMoves": {
            "e4": { "games": 96, "wins": 62, "draws": 28, "losses": 6, "frequency": 0.615, "winRate": 0.646 }
        },
        "topEcos": [
            { "eco": "C65", "name": "Ruy Lopez: Berlin Defense", "games": 42, "winRate": 0.69, "frequency": 0.269 }
        ],
        "openingTree": {
            "e4": {
                "games": 96,
                "wins": 62,
                "draws": 28,
                "losses": 6,
                "winRate": 0.646,
                "continuations": {
                    "e5": { "games": 48, "winRate": 0.625, "continuations": {} },
                    "c5": { "games": 32, "winRate": 0.688, "continuations": {} }
                }
            }
        }
    },
    "black": {
        "games": 156,
        "firstMoves": {
            "vs1e4": { "e5": { "games": 42, "frequency": 0.41, "winRate": 0.571 } },
            "vs1d4": { "Nf6": { "games": 38, "frequency": 0.37, "winRate": 0.605 } },
            "vs1c4": {},
            "vs1Nf3": {}
        }
    },
    "performanceByTimeControl": {
        "rapid": { "games": 200, "winRate": 0.60 },
        "blitz": { "games": 112, "winRate": 0.527 }
    },
    "recentTrends": [
        {
            "eco": "B12",
            "name": "Caro-Kann Defense",
            "trend": "increasing",
            "last30Games": 8,
            "prev60Games": 3,
            "recentRate": 0.267,
            "prevRate": 0.05
        }
    ],
    "surprises": [
        {
            "eco": "A00",
            "name": "Larsen Opening",
            "firstSeenRecently": "2024-11-01",
            "recentGames": 3,
            "historicalGames": 1,
            "historicalRate": 0.008
        }
    ],
    "rareRepeated": [
        { "eco": "C10", "name": "French Defense", "games": 4, "frequency": 0.026 }
    ],
    "pgnExport": null,
    "scrapedAt": "2024-12-21T14:30:00.000Z"
}

Results can be downloaded as JSON or CSV from the Output tab, or fetched programmatically via the Apify API.

---

Are There Other Chess Tools on Apify Store?

• Chess Ratings Aggregator -- Aggregate FIDE, Chess.com, and Lichess ratings for the top 100+ players side-by-side with 12-month progression and peak ratings
• Apify Store -- Browse hundreds of other scrapers and data tools

---

Frequently Asked Questions

Can I analyze any Lichess player with the Chess Opponent Analyzer?

Yes. Any public Lichess profile is available without authentication. Simply enter the username. For players with a large game history, add a Lichess API token in the lichessApiToken field to avoid rate limiting when fetching large game sets.

How many games can I analyze per run?

Up to 1,500 games per run, set via maxGames. For most players 200--500 games is sufficient for statistically reliable opening frequencies. Use higher values for players with rare sidelines or when preparing for very specific lines.

Does the Chess Opponent Analyzer work for Chess.com players?

Chess.com support is planned for Phase 2. The current version fetches from Lichess only. Many professional players have active Lichess accounts: Magnus Carlsen plays as DrNykterstein, Hikaru Nakamura as Hikaru, and Nihal Sarin as nihalsarin.

What is the opening tree depth setting?

Opening tree depth is measured in plies (half-moves). 12 plies = 6 full moves, which covers most standard opening theory. Use 20--24 plies for deep line preparation (for example, studying a player's handling of a specific 10-move variation). Higher depth produces larger output but gives more precise preparation signals.

Can I export games to Chessbase or Stockfish?

Yes. Enable exportPgn: true in the input. The actor saves all fetched games as a standard PGN file to the Apify key-value store and includes the download URL in the output under pgnExport. You can load this file directly into Chessbase, Arena, Lichess Study, or any PGN viewer.

How do I schedule regular analysis runs before a tournament?

Use the Apify scheduler to run the actor automatically. A recommended schedule for tournament preparation is once per week starting 4 weeks before the event, then daily in the final week. The recentTrends and surprises arrays are the key fields to monitor -- they will change if the opponent is actively preparing new lines.

Can I use the Chess Opponent Analyzer with the Apify API?

Yes. Every Apify actor is accessible via REST API. Send a POST request to https://api.apify.com/v2/acts/trovevault~chess-opponent-analyzer/runs with your input JSON and API token. Use the datasetId parameter to accumulate results for multiple players into a single dataset for comparison.

Can I use the Chess Opponent Analyzer through an MCP Server?

Yes. Apify provides a Model Context Protocol (MCP) server at mcp.apify.com that exposes all store actors as tools. Connect any MCP-compatible client (Claude, Cursor, etc.) to run the Chess Opponent Analyzer directly from your AI assistant. This is useful for automated preparation workflows where you ask your AI to analyze several opponents in one session.

Is this data analysis legal?

Yes. The Chess Opponent Analyzer only processes publicly available game data from Lichess, which explicitly provides a free public API for this purpose. All games played on Lichess are public by default and the Lichess API terms of use permit automated access for analysis. No private data, account credentials, or paid content are accessed.

What if the actor returns no results?

The most common cause is filters that are too strict. If gamesAnalyzed: 0 is returned, try: removing the minOpponentRating filter, expanding the date range, including more time controls, or using rated: "all". The error record includes a fix field with specific recommendations.

---

Your Feedback

Found a bug or have a feature request? Open an issue on the actor's Issues tab. Phase 2 (Chess.com support) and Phase 3 (official tournament games via TWIC) are on the roadmap -- upvote or comment to help prioritize.