# Chess Ratings Aggregator (`trovevault/chess-ratings-aggregator`) Actor Aggregate chess player ratings from FIDE, Chess.com, Lichess, and 2700chess into one dataset. Compare ratings side-by-side, track 12-month progression, peak ratings, gap analysis, and age efficiency. - **URL**: https://apify.com/trovevault/chess-ratings-aggregator.md - **Developed by:** [Trove Vault](https://apify.com/trovevault) (community) - **Categories:** Other, Integrations, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.28 / 1,000 players This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Chess Ratings Aggregator Aggregate chess player ratings from FIDE, Chess.com, Lichess, and 2700chess into one unified dataset. Compare ratings across sources side-by-side, track 12-month rating progression, detect prodigies and veterans, measure gap to the top. Built for chess journalists, content creators, researchers, and federations who need cross-platform chess data without manually hopping between sites. --- ### What does Chess Ratings Aggregator do? Chess Ratings Aggregator fetches chess player ratings from four sources and returns a consolidated dataset with one row per player. No single chess data service does this aggregation today. - **FIDE ratings** - Classical, rapid, and blitz ratings from the official FIDE top lists (scraped from ratings.fide.com) - **Chess.com ratings** - Bullet, blitz, rapid, and daily ratings from the public Chess.com API, plus FIDE rating from Chess.com's integrated profile - **Lichess ratings** - Classical, rapid, blitz, and bullet ratings with daily rating history for the last 12 months - **2700chess live ratings** - Opt-in live classical ratings (browser-based, uses residential proxy) - **Peak ratings** - All-time peak rating per time control where available - **Rating progression** - Last 12 months of monthly (FIDE) and daily (Lichess) rating points - **Insights per player** - Gap to #1, gap to next rank, rating trend, age/rating efficiency classification --- ### What data does Chess Ratings Aggregator return? One row per player with nested ratings: | Field | Description | |---|---| | `name` | Player name in FIDE format | | `fideId` | FIDE ID (canonical identifier) | | `country` | ISO3 country code | | `title` | GM, IM, FM, WGM, etc. | | `age` | Current age | | `ratings.fide` | FIDE ratings and rank by time control, with peak | | `ratings.chessCom` | Chess.com ratings with peak, plus FIDE rating shown on Chess.com profile | | `ratings.lichess` | Lichess ratings per time control with games count | | `ratings.twoSevenHundred` | 2700chess live classical rating (opt-in) | | `ratingHistory` | 12-month monthly (FIDE) and daily (Lichess) rating points | | `insights.gapToTop` | Rating points behind world #1 | | `insights.gapToNext` | Rating points to the next higher-ranked player | | `insights.ratingTrend12m` | Rating change over last 12 months | | `insights.ageEfficiency` | "prodigy" (age<20, rating>2700), "veteran" (age>=50, rating>=2600), or "peak-age" | --- ### How does Chess Ratings Aggregator work? 1. Fetches the FIDE top list for the selected time control (classical, rapid, or blitz) 2. Loads Chess.com and Lichess leaderboards in parallel for player matching 3. Matches FIDE players to their Chess.com and Lichess usernames using a curated seed mapping plus fuzzy name matching (Levenshtein + country boost) 4. Enriches each player with Chess.com stats, Lichess ratings, and rating history 5. Optionally scrapes 2700chess via browser when `include2700chess` is enabled 6. Computes per-player insights (rating gaps, trends, age efficiency) 7. Returns one row per player with everything merged Player matching uses a hardcoded seed for the top ~20 players (confirmed Chess.com/Lichess usernames) and fuzzy name matching for the rest. Outside the top 20, Chess.com and Lichess data may be missing if the usernames cannot be matched reliably. --- ### Why use Chess Ratings Aggregator instead of visiting each site? | Feature | Visit each site manually | Chess Ratings Aggregator | |---|---|---| | Sources covered | FIDE + Chess.com + Lichess + 2700chess (4 tabs) | All four in one output | | Rating comparison | Manual copy-paste into spreadsheet | Side-by-side per player | | Rating history | Not exposed on most sites | 12 months monthly + daily | | Peak rating | Only on FIDE profile | Included per source | | Gap analysis | Not available | Gap to #1, gap to next rank | | Age classification | Manual calculation | Prodigy, veteran, peak-age tags | | Country filter | Only on FIDE | On every source | | API access | Chess.com and Lichess only | Full Apify API on aggregated output | --- ### How to use Chess Ratings Aggregator? 1. [Create an Apify account](https://console.apify.com/sign-up) using your email 2. Open Chess Ratings Aggregator in Apify Store 3. Choose mode: **Top players** for a leaderboard, **Single player lookup** to find one specific player 4. Pick the time control (classical, rapid, blitz, or all) 5. Optionally filter by country or gender 6. Click **Start** - results appear in the output dataset --- ### Input example #### Top 20 classical players with Chess.com and Lichess enrichment ```json { "mode": "top", "topN": 20, "timeControl": "classical", "includeChessCom": true, "includeLichess": true, "includeRatingHistory": true } ```` #### Single player lookup by name ```json { "mode": "player", "playerName": "Magnus Carlsen", "includeChessCom": true, "includeLichess": true, "includeRatingHistory": true } ``` #### Top 50 women classical players from India ```json { "mode": "top", "topN": 50, "timeControl": "classical", "filterByGender": "women", "filterByCountry": ["IND"] } ``` *** ### Output example ```json { "name": "Carlsen, Magnus", "fideId": "1503014", "country": "NOR", "title": "GM", "age": 36, "ratings": { "fide": { "classical": { "rating": 2840, "rank": 1, "peak": { "rating": 2882, "year": 2014 } } }, "chessCom": { "username": "MagnusCarlsen", "fideFromChessCom": 2882, "bullet": { "rating": 3377, "peak": 3401 }, "blitz": { "rating": 3213, "peak": 3280 }, "rapid": { "rating": 2941, "peak": 2977 } }, "lichess": { "username": "DrNykterstein", "title": "GM", "blitz": { "rating": 3153, "games": 5421 }, "bullet": { "rating": 3197, "games": 8922 }, "classical": { "rating": 2500, "games": 47 } } }, "ratingHistory": { "fide_classical": [ { "month": "2025-04", "rating": 2830 }, { "month": "2026-04", "rating": 2840 } ] }, "insights": { "gapToNext": 0, "gapToTop": 0, "ratingTrend12m": 10, "ageEfficiency": "peak-age" }, "scrapedAt": "2026-04-12T15:00:00.000Z" } ``` *** ### How much does Chess Ratings Aggregator cost? Cost scales linearly with `topN`: - **FIDE scraping** - downloads the official full FIDE rating list (standard, rapid, or blitz) and ranks/filter players locally, plus 1 request per profile when `includeRatingHistory: true`. No proxy needed. - **Chess.com API** - free, 1 request per player for stats. No cost. - **Lichess API** - free, 2 requests per player (user + rating history). No cost. - **2700chess** - opt-in only. Requires residential proxy. Adds approximately 0.30 USD per run. A typical `topN: 100` run takes 3-5 minutes and costs around 0.05-0.10 USD without 2700chess. *** ### Are there other e-commerce and data tools in Apify Store? - [E-commerce Scraping Tool](https://apify.com/apify/e-commerce-scraping-tool) - Scrape product data, prices, and reviews from any e-commerce site - [Amazon Review Unmet Needs Extractor](https://apify.com/trovevault/amazon-review-unmet-needs-extractor) - Identify recurring product gaps from Amazon reviews using AI or keyword frequency - [Product Matching Vectorizer](https://apify.com/tri_angle/product-matching-vectorizer) - Build vector indexes from product catalogs for similarity matching *** ### Frequently asked questions #### Which chess rating sources does Chess Ratings Aggregator support? Chess Ratings Aggregator supports FIDE (ratings.fide.com), Chess.com (api.chess.com), Lichess (lichess.org/api), and optionally 2700chess.com (via browser due to Cloudflare). Freestyle Chess is not supported in v0.1 because there is no public ranking page. #### Why do some players show FIDE data only? Matching FIDE players to their Chess.com and Lichess usernames is challenging because there is no universal mapping. Chess Ratings Aggregator uses a seed mapping for the top ~20 confirmed players plus fuzzy name matching for the rest. Outside the top 20, Chess.com and Lichess data may be missing. Contact us to add more players to the seed mapping. #### How is "age efficiency" calculated? The `ageEfficiency` field is a simple classification based on age and current rating: "prodigy" for players under 20 rated above 2700, "veteran" for players 50 or older rated above 2600, and "peak-age" for players between 25 and 40. #### Can Chess Ratings Aggregator lookup a single player by name? Yes. Set `mode: "player"` and provide `playerName` (e.g., "Magnus Carlsen" or "Carlsen, Magnus") or `fideId`. The actor fetches full data for that one player across all sources. #### How far back does rating history go? The last 12 months. FIDE rating history is monthly granularity (12 data points per player). Lichess rating history is per-day (can be hundreds of points per player for active players). #### Can I use Chess Ratings Aggregator through an MCP Server? Yes. Connect via the [Apify MCP server](https://blog.apify.com/how-to-use-mcp/) for use with Claude Desktop, Claude Code, or any MCP-compatible AI assistant. #### Can I use Chess Ratings Aggregator with the Apify API? Yes. The [Apify API](https://docs.apify.com/api/v2) gives you programmatic access to run Chess Ratings Aggregator, schedule monthly updates, and pipe the output to your database or dashboard. #### Is scraping FIDE and 2700chess legal? Chess Ratings Aggregator only reads publicly available ratings pages. No authentication bypass, no private data. Chess.com and Lichess are accessed via their official free public APIs. Read more about the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). *** ### Your feedback Found a bug, need a player added to the seed mapping, or want a new source supported? [Create an issue](https://console.apify.com) on the Actor page. # Actor input Schema ## `mode` (type: `string`): Choose 'Top players' to fetch a leaderboard of top N players, or 'Single player' to look up one player by name or FIDE ID across all sources. ## `topN` (type: `integer`): Number of top players to fetch when mode is 'Top players'. Default 100. Uses FIDE's official full rating list download, so values like 500 or country-specific top 10s are supported, with runtime scaling roughly linearly. ## `playerName` (type: `string`): When mode is 'Single player', the player's name (FIDE format 'Lastname, Firstname' or common format 'Firstname Lastname'). Ignored in 'Top players' mode. ## `fideId` (type: `string`): Alternative to player name when mode is 'Single player'. Most reliable lookup method - e.g. 1503014 for Magnus Carlsen. ## `timeControl` (type: `string`): Primary time control for FIDE top list ranking. Chess.com and Lichess return all time controls regardless of this setting. ## `filterByCountry` (type: `array`): ISO3 country codes to filter by (e.g. NOR, USA, IND). Leave empty for all countries. ## `filterByGender` (type: `string`): Filter by gender in FIDE data. 'All' returns both, 'Women' uses FIDE women's top lists, 'Men' uses open lists (which can include women). ## `includeChessCom` (type: `boolean`): Fetch Chess.com ratings (bullet, blitz, rapid) and FIDE rating from Chess.com profile. Uses free public API. ## `includeLichess` (type: `boolean`): Fetch Lichess ratings (classical, rapid, blitz, bullet) and per-day rating history. Uses free public API. ## `include2700chess` (type: `boolean`): Fetch live classical ratings from 2700chess.com. Requires PlaywrightCrawler with residential proxy to bypass Cloudflare. Adds approximately 0.30 USD to run cost and 2 minutes runtime. Opt-in. ## `datasetId` (type: `string`): ID of an existing Apify dataset to push results into in addition to the default dataset. Useful for chaining with downstream actors. ## `runId` (type: `string`): ID of a previous actor run to associate this run with. Used for chaining actors in multi-step pipelines. ## Actor input object example ```json { "mode": "top", "topN": 100, "timeControl": "classical", "filterByCountry": [], "filterByGender": "all", "includeChessCom": true, "includeLichess": true, "include2700chess": false } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("trovevault/chess-ratings-aggregator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("trovevault/chess-ratings-aggregator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call trovevault/chess-ratings-aggregator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=trovevault/chess-ratings-aggregator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Chess Ratings Aggregator", "description": "Aggregate chess player ratings from FIDE, Chess.com, Lichess, and 2700chess into one dataset. Compare ratings side-by-side, track 12-month progression, peak ratings, gap analysis, and age efficiency.", "version": "0.1", "x-build-id": "foa7m1QJbl8XbKmnT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trovevault~chess-ratings-aggregator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trovevault-chess-ratings-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/trovevault~chess-ratings-aggregator/runs": { "post": { "operationId": "runs-sync-trovevault-chess-ratings-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/trovevault~chess-ratings-aggregator/run-sync": { "post": { "operationId": "run-sync-trovevault-chess-ratings-aggregator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "top", "player" ], "type": "string", "description": "Choose 'Top players' to fetch a leaderboard of top N players, or 'Single player' to look up one player by name or FIDE ID across all sources.", "default": "top" }, "topN": { "title": "Number of top players", "minimum": 1, "type": "integer", "description": "Number of top players to fetch when mode is 'Top players'. Default 100. Uses FIDE's official full rating list download, so values like 500 or country-specific top 10s are supported, with runtime scaling roughly linearly.", "default": 100 }, "playerName": { "title": "Player name", "type": "string", "description": "When mode is 'Single player', the player's name (FIDE format 'Lastname, Firstname' or common format 'Firstname Lastname'). Ignored in 'Top players' mode." }, "fideId": { "title": "FIDE ID (optional)", "type": "string", "description": "Alternative to player name when mode is 'Single player'. Most reliable lookup method - e.g. 1503014 for Magnus Carlsen." }, "timeControl": { "title": "Time control", "enum": [ "classical", "rapid", "blitz", "all" ], "type": "string", "description": "Primary time control for FIDE top list ranking. Chess.com and Lichess return all time controls regardless of this setting.", "default": "classical" }, "filterByCountry": { "title": "Country filter", "type": "array", "description": "ISO3 country codes to filter by (e.g. NOR, USA, IND). Leave empty for all countries.", "default": [], "items": { "type": "string" } }, "filterByGender": { "title": "Gender filter", "enum": [ "all", "men", "women" ], "type": "string", "description": "Filter by gender in FIDE data. 'All' returns both, 'Women' uses FIDE women's top lists, 'Men' uses open lists (which can include women).", "default": "all" }, "includeChessCom": { "title": "Include Chess.com ratings", "type": "boolean", "description": "Fetch Chess.com ratings (bullet, blitz, rapid) and FIDE rating from Chess.com profile. Uses free public API.", "default": true }, "includeLichess": { "title": "Include Lichess ratings", "type": "boolean", "description": "Fetch Lichess ratings (classical, rapid, blitz, bullet) and per-day rating history. Uses free public API.", "default": true }, "include2700chess": { "title": "Include 2700chess live ratings", "type": "boolean", "description": "Fetch live classical ratings from 2700chess.com. Requires PlaywrightCrawler with residential proxy to bypass Cloudflare. Adds approximately 0.30 USD to run cost and 2 minutes runtime. Opt-in.", "default": false }, "datasetId": { "title": "Dataset ID (optional)", "type": "string", "description": "ID of an existing Apify dataset to push results into in addition to the default dataset. Useful for chaining with downstream actors." }, "runId": { "title": "Run ID (optional)", "type": "string", "description": "ID of a previous actor run to associate this run with. Used for chaining actors in multi-step pipelines." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```