Chess Puzzle Analyzer - Fetch & Analyze Lichess Puzzles via API

An Apify Actor that programmatically retrieves and analyzes chess puzzles from the Lichess API. It's built on the Python Apify SDK template, providing a structured foundation for web scraping and data processing tasks.

Overview

This Actor connects to the Lichess puzzle database, fetches puzzles based on configurable parameters, and outputs structured data for analysis. It's designed for developers, analysts, or chess enthusiasts who need to collect puzzle data in an automated, scalable way.

Key Features

• Lichess API Integration: Directly fetches puzzles from the official Lichess puzzle API.
• Structured Data Output: Saves results into an Apify Dataset for easy export and integration.
• Configurable Input: Control puzzle selection via input parameters like rating range, themes, and limits.
• Built on Apify SDK: Utilizes the Python Apify SDK for robust queue management, error handling, and storage.
• Input Schema: Validates run configuration using a defined JSON schema.

How to Use

You can run the Actor directly in the Apify Console or integrate it via API.

1. Configure Input: Set your desired parameters in the Actor's input (e.g., minRating, maxRating, themes, maxPuzzles).
2. Run the Actor: Start a run in the console or via the API. The Actor will fetch puzzles matching your criteria.
3. Get Results: Download the structured puzzle data from the Dataset tab in various formats (JSON, CSV, Excel, etc.) or retrieve it via the Apify API.

Local Development

To modify or extend the Actor locally, pull the source code using the Apify CLI:

# Install the CLI
npm -g install apify-cli

# Pull the Actor to your current directory
apify pull <YourActorId>

Find your Actor's unique ID or name in the Apify Console. Develop within the async with Actor: block in main.py, leveraging the Apify SDK and any Python libraries.

Input / Output

Input (Configuration):
The Actor accepts a JSON input specifying puzzle fetch criteria. Typical parameters include:
* maxPuzzles: The total number of puzzles to retrieve.
* minRating / maxRating: The Elo rating range for puzzles.
* themes: An array of puzzle themes (e.g., ["middlegame", "pin"]).

Output (Dataset):
Each item in the output dataset represents a Lichess puzzle and contains structured fields such as:
* PuzzleId: The unique Lichess puzzle identifier.
* FEN: The board position in Forsyth–Edwards Notation.
* Moves: The solution sequence in UCI format.
* Rating: The puzzle's Elo rating.
* RatingDeviation: The uncertainty of the rating.
* Popularity: A popularity score.
* Themes: A list of associated tactical themes.
* GameUrl: A link to the source game.

Resources

• Apify SDK for Python documentation
• Apify Platform documentation
• Python tutorials in Academy
• Join our developer community on Discord