Lichess Scraper · Players, Games, Ratings & Tournaments

Scrape Lichess player profiles, rating leaderboards across 13 game variants (Bullet, Blitz, Rapid, Classical, UltraBullet, Chess960, Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, Three-Check), FIDE titles (GM, WGM, IM, WIM, FM, WFM, CM, WCM), country rankings, total games, play time, and profile metadata. Extracts structured data directly from the official public Lichess API over plain HTTP with no login or API key required.

Maintained by reapX. Every row cites the Apify run that produced it — nothing is inferred, modelled or filled in, and a field absent from the source is absent from the row. The extracted archive for this source is browsable at reapx.dev/data/lichess-scraper/ and mirrored as an open dataset on Hugging Face and Kaggle. Questions: reapxdev@proton.me

---

Overview & Key Features

Lichess Scraper is a production-ready, high-speed scraper designed to extract comprehensive chess player statistics, ratings, and profile metadata from Lichess.org. Built specifically for data scientists, chess researchers, tournament organizers, and gaming analysts, this actor collects clean, addressable player records without relying on browser automation or headful scraping.

Feature Highlights

• 13 Game Variants Supported: Scrape top players across standard time controls (Bullet, Blitz, Rapid, Classical) and specialized chess variants (UltraBullet, Chess960 / Fischer Random, Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, Three-Check).
• Official Title Filtering: Filter by FIDE and Lichess titles including Grandmaster (GM), Woman Grandmaster (WGM), International Master (IM), Woman International Master (WIM), FIDE Master (FM), Woman FIDE Master (WFM), Candidate Master (CM), Woman Candidate Master (WCM), and official BOT accounts.
• Geographic & Rating Search: Search and filter players by ISO 2-letter country code (US, NO, IN, FR, DE, ES, RU, CN, etc.) and custom minimum/maximum rating thresholds.
• Team Scrape Support: Extract profiles for members of official or custom Lichess teams (e.g., titled-players, all-grandmasters).
• Direct Handle Scrapes: Target specific Lichess usernames directly to fetch full multi-variant rating matrices and play history.
• Pay-Per-Event Billing: Pay only for complete player records returned. Empty results or rate-limited errors incur zero charge.

---

⬇️ Input

The actor accepts structured JSON input specifying game variant filters, title filters, country codes, rating limits, specific player handles, or team memberships.

Parameter	Type	Required	Default	Description
perfType	String	No	"bullet"	Game variant filter. Leaderboard mode: bullet, blitz, rapid, classical, ultraBullet, crazyhouse, chess960, kingOfTheHill, threeCheck, antichess, atomic, horde, racingKings, or all.
titleFilter	String	No	"all"	Title filter. Filter players by title: all, GM, WGM, IM, WIM, FM, WFM, CM, WCM, or BOT.
countryFilter	String	No	""	Country filter. Filter by ISO 2-letter country code (e.g. US, NO, IN, FR, DE, ES, RU, CN).
minRating	Integer	No	0	Minimum rating limit. Lower threshold for player ratings across active variants.
maxRating	Integer	No	4000	Maximum rating limit. Upper rating ceiling for player records.
usernames	Array	No	[]	Target Lichess usernames. Array of exact handles to fetch profiles directly.
teamId	String	No	""	Lichess Team ID. Optional team slug (e.g., titled-players or all-grandmasters) to fetch members from.
maxItems	Integer	Yes	100	Maximum player records. Hard limit on total player records scraped and saved to the dataset.

Example Input Configurations

1. Top Grandmasters in Blitz

{
  "perfType": "blitz",
  "titleFilter": "GM",
  "minRating": 2700,
  "maxItems": 100
}

2. Top Norwegian Players in Bullet

{
  "perfType": "bullet",
  "countryFilter": "NO",
  "maxItems": 50
}

3. Specific Player Handles

{
  "usernames": ["DrNykterstein", "resemble", "Penguinim", "RebeccaHarris", "MagnusCarlsen"],
  "maxItems": 50
}

4. Official All-Grandmasters Team

{
  "teamId": "all-grandmasters",
  "maxItems": 200
}

---

⬆️ Output

Scraped player records are written directly to the run's default dataset. Each row represents a unique Lichess player entity identified by their addressable handle (handle).

Dataset Schema Fields

Field Name	Type	Description	Example
handle	String	Unique Lichess player handle / username identifying the player entity.	"DrNykterstein"
username	String	Display username of the Lichess account.	"DrNykterstein"
title	String	Official FIDE or Lichess chess title (GM, WGM, IM, WIM, FM, WFM, CM, WCM, BOT).	"GM"
bulletRating	Integer	Current Lichess rating in Bullet chess (1-minute / fast games).	3243
blitzRating	Integer	Current Lichess rating in Blitz chess (3-5 minute games).	3153
rapidRating	Integer	Current Lichess rating in Rapid chess (10+ minute games).	2500
classicalRating	Integer	Current Lichess rating in Classical chess (long games).	2500
ultraBulletRating	Integer	Current Lichess rating in UltraBullet chess (30-second games).	2406
chess960Rating	Integer	Current Lichess rating in Chess960 / Fischer Random variant.	2541
crazyhouseRating	Integer	Current Lichess rating in Crazyhouse variant.	2756
antichessRating	Integer	Current Lichess rating in Antichess / Giveaway variant.	2291
atomicRating	Integer	Current Lichess rating in Atomic variant.	2465
hordeRating	Integer	Current Lichess rating in Horde variant.	2890
kingOfTheHillRating	Integer	Current Lichess rating in King of the Hill variant.	2836
racingKingsRating	Integer	Current Lichess rating in Racing Kings variant.	2433
threeCheckRating	Integer	Current Lichess rating in Three-Check variant.	2727
totalGames	Integer	Total number of games played across all Lichess variants.	10435
totalPlayTimeSeconds	Integer	Cumulative total play time on Lichess in seconds.	1169601
country	String	ISO two-letter country code set on user profile.	"NO"
profileName	String	Real name or display name listed in user profile.	"Magnus Carlsen"
bio	String	User profile biography snippet.	"World Chess Champion"
isPatron	Boolean	Whether the user supports Lichess as a patron.	true
isVerified	Boolean	Whether the Lichess account is officially verified.	true
createdAt	String	ISO timestamp when the account was registered.	"2018-12-06T12:44:50.814Z"
seenAt	String	ISO timestamp when the account was last active.	"2026-08-03T18:00:00.000Z"
url	String	Canonical web URL to the player profile on Lichess.	"https://lichess.org/@/DrNykterstein"

Example Output Record

{
  "handle": "DrNykterstein",
  "username": "DrNykterstein",
  "title": "GM",
  "bulletRating": 3243,
  "blitzRating": 3153,
  "rapidRating": 2500,
  "classicalRating": 2500,
  "ultraBulletRating": 2406,
  "chess960Rating": 2541,
  "crazyhouseRating": 2756,
  "antichessRating": 2291,
  "atomicRating": 2465,
  "hordeRating": 2890,
  "kingOfTheHillRating": 2836,
  "racingKingsRating": 2433,
  "threeCheckRating": 2727,
  "totalGames": 10435,
  "totalPlayTimeSeconds": 1169601,
  "country": "NO",
  "profileName": "Magnus Carlsen",
  "bio": "World Chess Champion",
  "isPatron": true,
  "isVerified": true,
  "createdAt": "2018-12-06T12:44:50.814Z",
  "seenAt": "2026-08-03T18:00:00.000Z",
  "url": "https://lichess.org/@/DrNykterstein"
}

---

Detailed Performance Variant Descriptions

Lichess supports standard chess and eight non-standard chess variants. Each variant maintains an independent Glicko-2 rating system:

1. Bullet: Fast-paced chess games with time controls under 3 minutes per player (most commonly 1+0 or 2+1).
2. Blitz: Rapid-tactical chess games with time controls from 3 to 10 minutes per player (most commonly 3+0 or 5+0).
3. Rapid: Standard speed chess with time controls from 10 to 25 minutes per player (most commonly 10+0 or 15+10).
4. Classical: Slow time control chess with 25+ minutes per player.
5. UltraBullet: Extreme speed chess with 30-second total clock per player (0.5+0).
6. Chess960 (Fischer Random): Shuffle chess invented by Bobby Fischer where starting piece positions on rank 1 and 8 are randomized.
7. Crazyhouse: Variant where captured enemy pieces change color and can be dropped onto any open square during your turn.
8. Antichess (Giveaway): Variant where capturing is mandatory, kings have no royal powers, and the objective is to lose all pieces.
9. Atomic: Variant where capturing causes an explosion that destroys the capturing piece, captured piece, and adjacent non-pawn pieces within a 1-square radius.
10. Horde: Asymmetrical variant where White plays with 36 pawns against Black's standard army.
11. King of the Hill: Variant where moving your king to one of the four center squares (d4, d5, e4, e5) wins the game immediately.
12. Racing Kings: Variant where both players race their kings to the 8th rank without putting kings in check.
13. Three-Check: Variant where checking the opponent's king three times wins the game.

---

How it works

1. Player Discovery: The actor connects to official Lichess API endpoints (/api/player/top/200/{perf}, /api/team/{teamId}/users, or direct input handles).
2. Batch User Profiles: Retrieves comprehensive user profile records in high-performance HTTP batches (POST /api/users), fetching ratings, play statistics, titles, countries, and profile bio data.
3. Filtering: Applies requested filters client-side (variant ratings, FIDE titles, country code, minimum/maximum rating thresholds).
4. Pay-Per-Event Billing: Charges exactly $0.002 per complete player record emitted to the default dataset (with tiered plan discounts down to $0.0008). Empty queries or rate-limited runs charge zero.
5. Streaming Output: Emits items continuously to the dataset in real-time as they are processed.

---

Code Examples

Python Integration (apify-client)

from apify_client import ApifyClient

# Initialize the ApifyClient with your API token
client = ApifyClient("YOUR_API_TOKEN")

# Prepare the Actor input
run_input = {
    "perfType": "blitz",
    "titleFilter": "GM",
    "countryFilter": "NO",
    "maxItems": 50
}

# Run the Actor and wait for it to finish
run = client.actor("reapx/lichess-scraper").call(run_input=run_input)

# Fetch dataset items
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['title']} {item['username']} - Blitz Rating: {item['blitzRating']}")

Node.js / JavaScript Integration (apify-client)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
    token: 'YOUR_API_TOKEN',
});

const input = {
    perfType: 'bullet',
    minRating: 2800,
    maxItems: 50,
};

const run = await client.actor('reapx/lichess-scraper').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

items.forEach((player) => {
    console.log(`${player.handle} (${player.country || 'N/A'}): ${player.bulletRating}`);
});

cURL API Example

curl -X POST "https://api.apify.com/v2/acts/reapx~lichess-scraper/runs?token=YOUR_API_TOKEN"      -H "Content-Type: application/json"      -d '{
           "perfType": "chess960",
           "maxItems": 100
         }'

---

❓ FAQ

1. Does this scraper require a Lichess account or API key?

No. All scraped endpoints are public open API surfaces provided by Lichess. No credentials or login cookies are required.

2. What game variants are supported?

All 13 official Lichess performance categories are supported: Bullet, Blitz, Rapid, Classical, UltraBullet, Chess960 (Fischer Random), Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, and Three-Check.

3. How does pricing work?

This actor uses Pay-Per-Event pricing. You are charged $0.002 per player record returned to your dataset. Discounted pricing tiers apply automatically based on your Apify subscription (Bronze, Silver, Gold, Platinum, Diamond). If an invalid query or rate limit occurs and zero rows are returned, nothing is charged.

4. How often is Lichess data updated?

Lichess leaderboards and user profiles update continuously in real-time as games complete on the platform.

5. Can I scrape members of a specific Lichess Team?

Yes. Pass the team ID slug into the teamId parameter (e.g. titled-players or all-grandmasters). The scraper will stream the team members and fetch full profile details for each member.

6. How are missing profile fields handled?

If a player has not configured a country code, biography, or real name, those fields will be returned as null in the dataset row without breaking schema structure.

7. What happens if a player account is closed or banned?

Disabled or closed accounts returned by discovery endpoints are formatted with available metadata. If profile lookup fails for a handle, it is skipped without stopping the run.

8. Is rate limiting handled automatically?

Yes. The scraper implements exponential backoff on HTTP 429 and HTTP 5xx responses, respecting Lichess server rate limit recommendations.

9. Can I export results to CSV or Excel?

Yes. Apify Console allows exporting the run dataset in JSON, CSV, Excel, XML, or HTML formats with custom column selection.

10. Where can I inspect historical archive data?

Extracted entity archives for this scraper are published and accessible at reapx.dev/data/lichess-scraper/ and mirrored as open datasets on Hugging Face and Kaggle.

---

Use Cases & Applications

• Grandmaster & Master Analytics: Track performance ratings of top GMs, IMs, and FMs across different speed chess formats.
• Chess Variant Research: Compare player skills and rating distributions across standard chess vs Chess960, Crazyhouse, and Atomic variants.
• Tournament Scouting: Prepare opponent data, favorite time controls, and total game counts for upcoming online tournaments.
• Bot Performance Monitoring: Track rating progression and activity levels of official automated chess engines.
• Geographic Chess Demographics: Analyze top player density and rating averages by country.

---

💬 Your feedback

Have questions, feature requests, or custom extraction needs? Contact the maintainers directly at reapxdev@proton.me.

---

Unofficial - not affiliated with Lichess. Collects public data only. reapx. Contact reapxdev@proton.me.

🧪 Example input

A real, runnable configuration — this is an actual input this Actor has run with.

{
  "perfType": "bullet",
  "titleFilter": "all",
  "countryFilter": "",
  "minRating": 0,
  "maxRating": 4000,
  "maxItems": 100
}

📄 Sample output

One real row from a real run of this Actor, unedited.

{
  "handle": "mraquariyaz67",
  "username": "mraquariyaz67",
  "title": "GM",
  "bulletRating": 3502,
  "blitzRating": 3027,
  "rapidRating": 2797,
  "classicalRating": 1499,
  "ultraBulletRating": 3000,
  "chess960Rating": 2937,
  "crazyhouseRating": 2756,
  "antichessRating": 2291,
  "atomicRating": 2465,
  "hordeRating": 2890,
  "kingOfTheHillRating": 2836,
  "racingKingsRating": 2433,
  "threeCheckRating": 2727,
  "totalGames": 12966,
  "totalPlayTimeSeconds": 918241,
  "country": null,
  "profileName": null,
  "bio": null,
  "isPatron": false,
  "isVerified": false,
  "createdAt": "2025-10-26T23:29:56.115000+00:00",
  "seenAt": "2026-08-01T10:00:54.307000+00:00",
  "url": "https://lichess.org/@/mraquariyaz67"
}

⚠️ Run outcomes and error handling

This Actor reports what happened in the run's status message, and it always keeps whatever it collected. These are the outcomes you can get and what each one means.

Outcome	What it means
Success	Rows were returned and you were charged record-returned at $0.002 per row.
No matches	The source returned nothing for your filters. Nothing is charged. Widen the date window or drop a filter.
Partial - source refused	The source rate-limited or refused some requests. The affected items are skipped and named in the log, and everything already collected is still pushed. A block never discards a run's work.
Rejected filter	The source itself rejected the filter combination. The run fails fast with the source's own reason and nothing is charged.

What is guaranteed either way

• Every row is pushed as it is built, not buffered to the end of the run. Anything that buffers output loses everything to a timeout, a block or a migration; this does not.
• A field absent from the source is absent from the row. Nothing is inferred, modelled or filled in to make a row look complete.