Chess.com and Lichess Scraper: Player Ratings, PGN Game History, and Leaderboards

This chess scraper reads the public Chess.com and Lichess APIs and saves player ratings, game history with PGN, leaderboards, titled-player lists, and club info. You can download JSON, CSV, or Excel, or send the dataset to Google Sheets, Make, Zapier, or n8n. There is no login.

Requests are strictly one at a time per site. Chess.com and Lichess can run at the same time as each other. That matches both sites' published rules. A 429 waits 60 seconds and retries once. A second 429 stops that site for the rest of the run. A Chess.com 410 is not requested again.

Use cases

• Chess coaches and scouts: pull an opponent's ratings and recent games before a match.
• Streamers: keep a public rating card and a stream link for the players you cover.
• Tournament organizers: export a Chess.com GM, IM, or FM list for invitations.
• Chess model and engine work: download rated games with PGN, openings, and Chess.com accuracies.
• Club admins: record member count, average daily rating, and admins for a Chess.com club.
• Sponsors: find titled streamers and the follower counts Chess.com publishes.

How to run it

1. Pick a mode and a platform. A bare username on "both" is looked up on Chess.com and on Lichess. A profile URL stays on that site.
2. For games, set a per-player cap. The newest months are read first.
3. Set the row cap. The free cap is 20,000 rows per run.
4. Start the run. A missing username becomes an error row and the run continues.

Input

Parameter	Type	Default	Description
mode	string	players	players, games, leaderboards, titled, club, country, or perf.
platform	string	both	chesscom, lichess, or both.
usernames	string[]	hikaru, DrNykterstein	Usernames or chess.com/member/ and lichess.org/@/ URLs.
includeClubs	boolean	false	Chess.com clubs on each player. Extra request per player.
gamesFromMonth	string	empty	Oldest month, YYYY-MM.
gamesToMonth	string	empty	Newest month, YYYY-MM.
timeClasses	string[]	empty	bullet, blitz, rapid, classical, daily, correspondence, ultraBullet.
includePgn	boolean	true	Store PGN on each game.
maxGamesPerPlayer	integer	200	Newest games kept. Maximum 5,000.
lichessPerf	string	blitz	Lichess leaderboard or perf type.
leaderboardSize	integer	100	Lichess top N. Maximum 200. Top 10 was the live check.
titles	string[]	GM	Chess.com title lists.
clubIds	string[]	empty	Club URL id or club page URL.
countryCodes	string[]	empty	ISO codes such as US.
enrichUsernames	boolean	false	Fetch profiles for titled and country usernames, inside the row cap.
maxItems	integer	500	Row cap. Maximum 20,000.
timeoutSecs	integer	300	Stop after this many seconds and keep saved rows.
requestTimeoutSecs	integer	30	Per-request timeout.
proxyConfiguration	object	No proxy	Leave off unless a site returns 403 or 429.

Player ratings

{
    "mode": "players",
    "platform": "both",
    "usernames": ["hikaru", "https://lichess.org/@/DrNykterstein"],
    "includeClubs": false
}

Games with PGN

{
    "mode": "games",
    "platform": "chesscom",
    "usernames": ["hikaru"],
    "gamesFromMonth": "2026-09",
    "gamesToMonth": "2026-09",
    "timeClasses": ["blitz"],
    "maxGamesPerPlayer": 50,
    "includePgn": true
}

Leaderboards, titles, clubs, countries, perf

{ "mode": "leaderboards", "platform": "lichess", "lichessPerf": "blitz", "leaderboardSize": 10 }

{ "mode": "titled", "platform": "chesscom", "titles": ["GM"], "maxItems": 200 }

{ "mode": "club", "platform": "chesscom", "clubIds": ["chess-com-developer-community"] }

{ "mode": "country", "platform": "chesscom", "countryCodes": ["US"], "maxItems": 100 }

{ "mode": "perf", "platform": "lichess", "usernames": ["DrNykterstein"], "lichessPerf": "blitz" }

What data does this actor extract?

Player rows include platform, username, displayName, profileUrl, title, country, followers, joinedAt, ratings, and blitzRating. Lichess rows also include gamesCount and playTimeTotalSec. Chess.com ratings cover bullet, blitz, rapid, daily, chess960, fide, tactics, and puzzle rush.

The player table uses playerTitle because Apify's dataset schema rejects the field name title. The JSON row still includes title. blitzRating is the same number as ratings.blitz.rating.

Game rows include both players, result (1-0, 0-1, or ½-½), timeClass, opening, Chess.com accuracies when the site sent them, and pgn when you leave that option on. Chess960 games keep initialSetup when the start position is not the standard one.

Leaderboard rows include board, rank, username, score, and profileUrl. Titled and country rows include listName and username. Club rows include membersCount, averageDailyRating, admins, and clubDescription. The club member list endpoint is not called. It returned an internal error in testing.

Failures use error and statusCode. Codes: NOT_FOUND, NO_DATA, HTTP_<code>, HTTP_410, RATE_LIMITED, PARSE_ERROR, INVALID_INPUT. The same player or game is saved once.

Limits and fair use

• One request at a time per site. Do not raise that. Both Chess.com and Lichess say parallel traffic can be blocked.
• On a 429 the actor waits 60 seconds, retries once, then stops that site.
• Chess.com says its published data refreshes at most once every 12 hours.
• Public APIs only. No login, no private games, and no password-protected content.
• Free runs cap at 20,000 rows, and at 5,000 games per player.
• For a full Lichess game dump, use the monthly database at https://database.lichess.org instead of paging the user export.
• The Lichess rating-history endpoint came back empty for the accounts we checked, so it is not used.
• Proxy stays off. One reused proxy is available if your IP is blocked. Rotating the address on every request is a bad fit for these APIs.

FAQ

Does this need a Chess.com or Lichess account? No. It uses the public published APIs.

Why is a username missing on one site? hikaru and DrNykterstein are not the same account on both sites. With platform set to both, a name that exists on only one site produces a NOT_FOUND row for the other.

Can I download every game a player has ever played? You can page monthly archives up to the per-player cap. A single Chess.com month can be hundreds of games. For all of Lichess, use database.lichess.org.

Why are emails and phone numbers not in the output? These APIs do not publish them.

What does a second 429 mean? That site asked us to slow down even after a one-minute wait. The actor stops calling it and keeps whatever it already saved. The other site is not affected.

Related

BigiByte also builds Twitch and YouTube creator actors if you want streamer audience data next to these ratings.

Need chess analytics dashboards, player scouting reports, or a custom game-data pipeline? BigiByte builds it: https://bigibyte.com

Trademark Notice

Chess.com and Lichess and related names, logos, and trademarks belong to their respective owners. Their use in this documentation is solely to identify the source of the data and does not imply affiliation, sponsorship, endorsement, or partnership.

Disclaimer

This Actor is an independent tool and is not affiliated with, endorsed by, sponsored by, or otherwise officially associated with Chess.com and Lichess.

Is web scraping legal?

Collecting information that is already public is generally legal. Scraping is not the same thing as hacking, and there is no single law that bans it. The limits are the usual ones: do not break into accounts, do not take private or confidential data, and be careful with personal data and copyrighted works. A site's terms can also restrict how you access it. Facts such as a public name, price, or rating are not the same thing as republishing someone's article or photo.

This actor reads public pages or official public APIs. It does not log in and it does not bypass access controls.

This is not legal advice. For the longer explanation, see Apify's article Is web scraping legal?.