Chess.com Player Game Archive Scraper
Chess.com Player Game Archive Scraper
Harvest complete game archives from Chess.com's fully open Published-Data API. Collect PGN notation, time controls, accuracy percentages, ECO opening codes, per-game ratings, player profiles, stats, and global leaderboards — all without any API key.
What does Chess.com Player Game Archive Scraper do?
This actor connects to Chess.com's Published-Data API and retrieves structured data across three modes:
- Games mode (default): Fetches a player's full profile, rating stats, and complete monthly game archives. Each game record includes the PGN with full move notation and clock times, time class (blitz/bullet/rapid/daily), ECO opening code, both players' ratings and results, and accuracy percentages when available.
- Profile mode: Returns player profile (title, country, join date, follower count) and current rating stats (blitz, bullet, rapid, daily, puzzle rush, FIDE, tactics) without fetching game archives.
- Leaderboards mode: Returns the current global leaderboard standings across all Chess.com time-control categories.
Why use Chess.com Player Game Archive Scraper?
Chess.com has over 150 million registered accounts and records millions of games per day. The platform's Published-Data API is fully open and requires no authentication, but accessing it at scale — thousands of games across multiple players and months — requires proper fan-out logic, rate management, and data normalization. This actor handles all of that so you can focus on your analysis.
Ideal use cases:
- Opening repertoire analysis across hundreds of games
- Rating progression tracking over custom date ranges
- Training data for chess engines or ML models
- Cheat-detection research (accuracy patterns, centipawn-loss analysis)
- Content creation (GM game breakdowns, tournament prep)
- Building chess analytics dashboards
How to use Chess.com Player Game Archive Scraper
Basic usage — scrape a player's recent games
- Set Usernames to the Chess.com handle(s) you want to scrape (e.g.
["hikaru", "magnuscarlsen"]). - Set Scrape Mode to
games. - Optionally set Date From and Date To (format:
YYYY-MM) to restrict the harvest to specific months. - Set Max Items to control output size.
Fetch a player profile and stats only
Set Scrape Mode to profile and provide one or more usernames. Returns rating history, membership status, and win/loss/draw records without fetching game archives.
Pull global leaderboards
Set Scrape Mode to leaderboards. No usernames required. Returns top-ranked players across all live and correspondence time controls.
Input parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
usernames |
Array of strings | Yes (for games/profile) | ["hikaru"] |
Chess.com usernames to scrape |
mode |
String | No | games |
Scrape mode: games, profile, or leaderboards |
dateFrom |
String | No | Earliest available | Start month for archive harvest, format YYYY-MM |
dateTo |
String | No | Current month | End month for archive harvest, format YYYY-MM |
maxItems |
Integer | Yes | 10 |
Maximum records to output |
Output schema
All records include a record_type field (game, profile, stats, or leaderboard) so you can filter results in downstream processing.
Game record fields: game_url, game_pgn, time_control, time_class, rules, rated, white_username, white_rating, white_result, black_username, black_rating, black_result, eco_code, eco_url, end_time, white_accuracy, black_accuracy
Profile record fields: username, player_id, title, name, country, location, followers, joined, last_online, status
Stats record fields: username, rating_blitz, rating_bullet, rating_rapid, rating_daily, rating_puzzle_rush, fide_rating, tactics_highest, record_wins, record_losses, record_draws
Leaderboard record fields: leaderboard_category, leaderboard_rank, leaderboard_score, username, player_id, title, name, country, status
Technical notes
- Uses Chess.com's open Published-Data API — no API key, no captcha, no login required.
- Sends a descriptive User-Agent per Chess.com's published etiquette guidelines.
- Concurrent month fetches (up to 3 parallel per username) with 300ms between batches.
- Automatic retry with backoff on 429 rate-limit responses.
- Proxy not required — the API is globally accessible via standard HTTPS.
- Memory: 512 MB (PGN strings can be large for high-volume players).