Chess.com Scraper — Players, Games, Leaderboards & Titled Player Lists

Extract comprehensive chess data from Chess.com's official Published-Data API. No API key or login required — just run and get thousands of structured rows.

What does Chess.com Scraper do?

Chess.com Scraper connects directly to the official Chess.com Published-Data API (api.chess.com/pub) and retrieves structured JSON data across five distinct modes: player games by month, player profiles with stats, global leaderboards, titled player rosters (GM/IM/FM/etc.), and country player lists. The engine sends descriptive User-Agent headers as required by Chess.com's API guidelines, handles rate limits gracefully with automatic retries, and runs player lookups in concurrent batches of 10 for maximum throughput. Monthly game archives allow bulk extraction — a single month for a prolific player can yield thousands of games, each with PGN, opening, ECO code, time control, ratings, and results. Pagination is handled automatically; you simply specify the range of months you want. No API key, credentials, or browser automation required.

Who is it for?

• Chess researchers and analysts building game databases or studying opening theory trends across thousands of games.
• Sports data vendors who need structured player rating and match result data for chess platforms or aggregators.
• Chess coaches and training platforms wanting to bulk-import GM game collections for study material.
• Developers and data scientists training machine learning models on chess positions, openings, or rating prediction.
• Fantasy chess app builders needing live leaderboard rankings and titled player rosters with up-to-date ratings.

Use cases

• Download all Grandmaster games played in a specific month for opening analysis pipelines.
• Build a searchable database of all active GMs with their rapid/blitz/bullet ratings and country affiliations.
• Monitor live global leaderboards for daily/weekly rating movement tracking.
• Bulk-extract player profiles from a country to study the distribution of chess skill within a nation.
• Populate a club management system with member rosters from Chess.com clubs.

Why use Chess.com Scraper?

• Fully keyless: Uses the official Chess.com Published-Data API — zero credentials needed.
• 30+ output fields: Game PGN, ECO, opening name, time class, ratings, results, player titles, follower counts, join dates, and more.
• High volume: One month of a top GM's games = 50–200+ rows. All GMs globally = 2,000+ profiles. Country players = tens of thousands.
• Five targeted modes: Switch between game scraping, profile lookup, leaderboards, titled players, or country players — all in one actor.
• Clean export: Download as JSON, CSV, or Excel from the Apify dataset for immediate use in spreadsheets or databases.
• Pay-per-result: Apify's pricing means you only pay for the compute you actually use.

What data can you extract?

Player / Profile fields

Field	Type	Description
mode	string	Scraping mode used
username	string	Chess.com username
name	string	Display name
title	string	Chess title (GM, IM, FM, etc.)
url	string	Profile URL
country	string	2-letter country code
followers	string	Follower count
joined	string	ISO8601 join date
status	string	Account status (premium, basic, etc.)
avatar	string	Avatar image URL
ratingRapid	string	Last rapid rating
ratingBlitz	string	Last blitz rating
ratingBullet	string	Last bullet rating
ratingChess960	string	Last Chess960 daily rating
rank	string	Leaderboard rank (leaderboards mode)
score	string	Leaderboard score

Game fields

Field	Type	Description
url	string	Game URL on Chess.com
pgn	string	Full PGN game notation
timeClass	string	rapid, blitz, bullet, daily, etc.
timeControl	string	Time control string (e.g. 180+2)
rated	string	true/false — whether rated
endTime	string	ISO8601 game end timestamp
whiteUsername	string	White player username
whiteRating	string	White player rating at time of game
whiteResult	string	win, lose, draw, resigned, etc.
blackUsername	string	Black player username
blackRating	string	Black player rating
blackResult	string	Game result for black
eco	string	ECO opening code (e.g. E60)
opening	string	Opening name from PGN

Sample JSON output (game)

{
  "mode": "playerGames",
  "url": "https://www.chess.com/game/live/12345678",
  "pgn": "[Event \"Live Chess\"][Site \"Chess.com\"]...",
  "timeClass": "blitz",
  "timeControl": "180+2",
  "rated": "true",
  "endTime": "2024-03-15T21:42:00.000Z",
  "whiteUsername": "magnuscarlsen",
  "whiteRating": "2882",
  "whiteResult": "win",
  "blackUsername": "hikaru",
  "blackRating": "3301",
  "blackResult": "resigned",
  "eco": "B92",
  "opening": "Sicilian Defense: Najdorf Variation"
}

Sample JSON output (player profile)

{
  "mode": "titledPlayers",
  "username": "magnuscarlsen",
  "name": "Magnus Carlsen",
  "title": "GM",
  "url": "https://www.chess.com/member/magnuscarlsen",
  "country": "NO",
  "followers": "82000",
  "joined": "2011-01-23T00:00:00.000Z",
  "status": "premium",
  "ratingRapid": "3000",
  "ratingBlitz": "3197",
  "ratingBullet": "3100",
  "ratingChess960": "2900"
}

How to use

Option A — Scrape all GM profiles

Set mode to titledPlayers and title to GM. The actor fetches all GMs registered on Chess.com and retrieves their full profile + stats.

{
  "mode": "titledPlayers",
  "title": "GM",
  "maxResults": 500
}

Option B — Scrape a player's monthly games

Set mode to playerGames, provide one or more usernames, and specify months in YYYY/MM format. Leave months empty to get last month automatically.

{
  "mode": "playerGames",
  "usernames": ["magnuscarlsen", "hikaru"],
  "months": ["2024/01", "2024/02", "2024/03"],
  "maxResults": 5000
}

Option C — Country players

Scrape all players registered under a country code. This can return thousands of usernames with full profile + stats.

{
  "mode": "countryPlayers",
  "country": "IN",
  "maxResults": 2000
}

Option D — Global leaderboards

Pull current leaderboard rankings across all time controls (rapid, blitz, bullet, tactics, etc.).

{
  "mode": "leaderboards",
  "maxResults": 500
}

Input parameters

Parameter	Type	Default	Description
mode	string	titledPlayers	Scraping mode: playerGames, playerProfile, leaderboards, titledPlayers, countryPlayers
usernames	array	[]	Chess.com usernames for playerGames/playerProfile modes
months	array	[]	Months to fetch (YYYY/MM). Default: last month
title	string	GM	Title for titledPlayers mode: GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM
country	string	US	ISO2 country code for countryPlayers mode
maxResults	integer	1000	Max rows to output (0 = unlimited)
proxyConfig	object	useApifyProxy: true	Apify proxy configuration

Full input JSON:

{
  "mode": "titledPlayers",
  "usernames": [],
  "months": [],
  "title": "GM",
  "country": "US",
  "maxResults": 1000,
  "proxyConfig": { "useApifyProxy": true }
}

Output example

[
  {
    "mode": "leaderboards",
    "username": "hikaru",
    "name": "Hikaru Nakamura",
    "title": "GM",
    "url": "https://www.chess.com/member/hikaru",
    "country": "US",
    "followers": "110000",
    "rank": "1",
    "score": "3301",
    "timeClass": "live_blitz"
  },
  {
    "mode": "playerGames",
    "url": "https://www.chess.com/game/live/98765432",
    "timeClass": "bullet",
    "timeControl": "60",
    "rated": "true",
    "endTime": "2024-06-01T14:33:00.000Z",
    "whiteUsername": "hikaru",
    "whiteRating": "3295",
    "whiteResult": "win",
    "blackUsername": "opponent123",
    "blackRating": "2800",
    "blackResult": "timeout",
    "eco": "C20",
    "opening": "King's Pawn Game"
  }
]

Tips for best results

• Use specific months: Specifying months reduces run time significantly — each month is one API call per player.
• Set maxResults: For country-player modes (e.g. India has 500k+ members), always set a maxResults to avoid very long runs.
• Combine modes: Run titledPlayers first to get usernames, then feed them into playerGames for deep game analysis.
• Rate limits: Chess.com allows ~1 request/second per IP. The actor batches 10 concurrent requests — runs fine on Apify's shared proxies.
• PGN parsing: The pgn field contains full PGN notation. Use a chess library (python-chess, chess.js) to parse positions, moves, and evaluations.
• ECO codes: Filter by eco to study specific openings across thousands of games (e.g. all Sicilian Najdorf games).
• Country codes: Use ISO 3166-1 alpha-2 codes (US, DE, IN, RU, TR, etc.) for the country field.
• Scheduled runs: Schedule monthly runs to keep your game database fresh. Use the Apify Scheduler or a webhook trigger.
• Export to Google Sheets: Connect your dataset to Google Sheets via Apify integrations for live-updating dashboards.
• Title ladder: Available titles: GM, WGM, IM, WIM, FM, WFM, NM (National Master), WNM, CM (Candidate Master), WCM.

Integrations

• Google Sheets: Use the Apify → Google Sheets integration to push extracted data directly into a spreadsheet. Keep a live leaderboard updated.
• Slack: Send notifications when a new GM game set is extracted using the Apify Webhook → Slack integration.
• Zapier / Make: Connect to 5,000+ apps. Trigger an email, update a CRM, or post to Discord when a run completes.
• Webhooks: Configure a webhook in the actor settings to call your own API endpoint after each run.
• Schedule: Use Apify Scheduler to run the actor daily or weekly for continuous data freshness.
• Apify API: Integrate directly via the REST API or official SDKs (Node.js, Python) for programmatic control.

API usage

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/logiover~chess-com-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"titledPlayers","title":"GM","maxResults":100}'

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('logiover/chess-com-scraper').call({
  mode: 'titledPlayers',
  title: 'GM',
  maxResults: 200,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("logiover/chess-com-scraper").call(run_input={
    "mode": "leaderboards",
    "maxResults": 100,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

Use with AI agents (MCP)

You can invoke this actor from any AI agent or LLM workflow using Apify's MCP server. Connect Claude, GPT-4, or any tool-calling agent to Apify MCP and prompt it: "Fetch all Grandmaster profiles from Chess.com and find the top 10 by blitz rating" — the agent will call this actor, receive structured JSON, and answer from real data. No code required.

FAQ

Does this actor require a Chess.com API key?

No. It uses the official Chess.com Published-Data API which is publicly accessible without any credentials.

How many results can I get per run?

Thousands to hundreds of thousands. The titledPlayers mode alone returns 2,000+ GM profiles. A single player's game history across 12 months can be 1,000–3,000 games.

What time controls are available for games?

The timeClass field returns: daily, chess960, rapid, blitz, bullet. The timeControl field gives the exact time+increment string.

What happens if a player has no games in the specified month?

The actor logs a warning and moves to the next month/player. Empty months produce zero rows for that player without crashing the run.

Can I get games for a specific time control only?

Not at the API level — Chess.com's archive returns all games for a month. Filter by timeClass in your data processing (e.g. Apify dataset filters or pandas).

What country codes are supported?

Any ISO 3166-1 alpha-2 code where Chess.com has registered players. Popular: US, RU, IN, DE, FR, TR, CN, BR, PL, UA.

How do I export data to Excel?

In the Apify dataset view, click the Download button and select XLSX. You can also use the API with format=xlsx.

What are the Chess.com API rate limits?

Chess.com requests a descriptive User-Agent and polite usage. This actor batches 10 concurrent requests and includes automatic retry on 429 responses. Runs are safe by design.

How often is Chess.com data updated?

Player profiles and stats are near real-time. Monthly game archives are complete for past months; the current month's archive grows daily.

Is there a risk of missing games?

Monthly game archives from past months are complete and stable. The current-month endpoint may not include the very latest games (Chess.com updates archives with a short delay).

Can I scrape club members?

Yes, use the clubId field (the URL slug of the club, e.g. chess-com-developer-community). The actor will enumerate members and fetch their profiles.

Why are some player profiles missing a title or rating?

Chess.com profiles may lack a title (unrated players), name (privacy setting), or stats in a time control if the player has never played it. The actor returns null for missing fields.

Is it legal?

Chess.com explicitly provides the Published-Data API for third-party use. This actor uses only that public API with proper User-Agent identification and respects rate limits. No scraping of the frontend HTML, no login bypass, and no access to private user data. Always review Chess.com's Terms of Service and API usage guidelines before using the data commercially.

Related scrapers

• Chess.com — official published data, this actor
• logiover/linkedin-company-scraper — Company profiles and employee counts without login
• logiover/leaderboard-tracker — Rank and score tracking across platforms
• logiover/b2b-lead-scraper — B2B lead generation from directories