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

1. Set Usernames to the Chess.com handle(s) you want to scrape (e.g. ["hikaru", "magnuscarlsen"]).
2. Set Scrape Mode to games.
3. Optionally set Date From and Date To (format: YYYY-MM) to restrict the harvest to specific months.
4. 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).