Chess Ratings Aggregator

Chess Ratings Aggregator combines chess player ratings from FIDE, Chess.com, Lichess, and optionally 2700chess into one dataset. It starts from FIDE official rating lists or a single player lookup, enriches matched players with online ratings, and returns side-by-side ratings, ranks, age, country, title, source usernames, and computed gap insights.

Use it for chess journalism, federation research, rating dashboards, player scouting, content production, or cross-platform player comparison without opening several rating sites manually.

Why use Chess Ratings Aggregator?

Chess ratings are split across official over-the-board lists and online platforms. This actor downloads the FIDE rating list, matches players to known Chess.com and Lichess accounts where possible, optionally checks 2700chess live ratings, and returns one normalized row per player.

Capability	Manual research	Chess Ratings Aggregator
Sources	Several websites and APIs	FIDE, Chess.com, Lichess, optional 2700chess
Input	Manual player lookups	Top N list or single player
Cross-platform comparison	Spreadsheet work	One dataset row per player
Country and gender filtering	Repeated searches	Built into FIDE selection
Gap analysis	Manual calculation	gapToTop and gapToNext
API access	Mixed by source	Apify dataset and API output

FIDE list or player -> match online usernames -> enrich ratings -> compute insights -> Apify dataset/API

What data does Chess Ratings Aggregator return?

Each dataset item represents one FIDE player. Chess.com, Lichess, and 2700chess fields are included only when a reliable account or live-rating match is found.

Field	What it means
name	Player name from FIDE
fideId	FIDE player ID
country	FIDE country code
gender	Gender inferred from FIDE list data
birthYear, age	Birth year and computed current age when available
ratings.fide	FIDE rating and rank for the selected time control
ratings.chessCom	Matched Chess.com username and bullet, blitz, rapid, daily, and FIDE profile ratings
ratings.lichess	Matched Lichess username and available bullet, blitz, rapid, classical, or correspondence ratings
ratings.twoSevenHundred	Optional 2700chess live classical rating
insights.gapToTop	Rating points behind the top player in the returned list
insights.gapToNext	Rating points behind the next higher returned player
insights.ageEfficiency	prodigy, veteran, peak-age, or null
runId	Optional parent workflow run ID copied from input
scrapedAt	ISO timestamp when the row was produced

What can you do with chess rating data?

• Compare elite players across sources by placing FIDE, Chess.com, Lichess, and optional 2700chess ratings in one table.
• Build country or federation reports with FIDE country filters and top N limits.
• Track online versus over-the-board gaps for players with matched Chess.com or Lichess accounts.
• Find rating-distance storylines with gapToTop, gapToNext, and age-based classifications.
• Create dashboards and recurring reports by scheduling runs and exporting JSON, CSV, or Excel.
• Power downstream workflows by appending rows to an existing Apify dataset with datasetId.

How do I aggregate chess ratings?

1. Choose Top players or Single player lookup.
2. For top lists, set topN, timeControl, and optional country or gender filters.
3. For one player, provide playerName or the more reliable fideId.
4. Leave Chess.com and Lichess enabled unless you only need FIDE data.
5. Enable include2700chess only when live classical ratings are worth the extra proxy/runtime cost.
6. Start the actor and export the dataset or read it through the Apify API.

What input does Chess Ratings Aggregator need?

{
  "mode": "top",
  "topN": 20,
  "timeControl": "classical",
  "filterByCountry": ["NOR"],
  "includeChessCom": true,
  "includeLichess": true,
  "include2700chess": false
}

Field	Type	Default	Description
mode	String	top	Use top for a FIDE leaderboard or player for one player lookup.
topN	Integer	100	Number of ranked FIDE players to return in top mode. Runtime scales roughly with this value.
playerName	String	blank	Player name for single-player mode. Accepts Magnus Carlsen or Carlsen, Magnus.
fideId	String	blank	FIDE ID for single-player mode. More reliable than name search.
timeControl	String	classical	FIDE ranking basis: classical, rapid, blitz, or all (currently uses classical for FIDE selection).
filterByCountry	Array	[]	ISO3 country codes such as NOR, USA, or IND. Empty means all countries.
filterByGender	String	all	all, men (open list), or women.
includeChessCom	Boolean	true	Fetch matched Chess.com ratings from the public API.
includeLichess	Boolean	true	Fetch matched Lichess ratings from the public API.
include2700chess	Boolean	false	Opt-in browser scrape of 2700chess live classical ratings using Residential proxy.
datasetId	String	blank	Optional existing dataset that also receives each row.
runId	String	blank	Optional parent workflow run ID copied into each row.

What does the output look like?

{
  "name": "Carlsen, Magnus",
  "fideId": "1503014",
  "country": "NOR",
  "gender": "male",
  "birthYear": 1990,
  "age": 35,
  "ratings": {
    "fide": {
      "classical": { "rating": 2839, "rank": 1 }
    },
    "chessCom": {
      "username": "MagnusCarlsen",
      "blitz": { "rating": 3213 },
      "rapid": { "rating": 2941 }
    },
    "lichess": {
      "username": "DrNykterstein",
      "blitz": { "rating": 3153, "games": 5421 }
    }
  },
  "insights": {
    "gapToNext": 0,
    "gapToTop": 0,
    "ageEfficiency": "peak-age"
  },
  "runId": "optional-parent-run-id",
  "scrapedAt": "2026-07-19T10:00:00.000Z"
}

How do I run Chess Ratings Aggregator via API?

Trigger a run with curl:

curl -X POST "https://api.apify.com/v2/acts/trovevault~chess-ratings-aggregator/runs" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"top","topN":20,"timeControl":"classical","includeChessCom":true,"includeLichess":true}'

After the run finishes, read results from the default dataset or the datasetId supplied in input.

How do I fix common chess rating aggregation issues?

Issue	Solution
No players returned	Loosen filterByCountry or filterByGender, reduce conflicting filters, and test topN: 10.
Single player not found	Use fideId instead of name. FIDE IDs are the most reliable lookup key.
Chess.com or Lichess data is missing	Matching depends on seed mappings and fuzzy name matching. Some FIDE players do not have reliable matched usernames.
2700chess is slow or missing	Keep include2700chess disabled unless needed. It uses browser automation and Residential proxy because the site can block automation.
Run takes longer than expected	Lower topN or disable optional sources. Larger FIDE batches and 2700chess add runtime.
Costs are higher than expected	Disable include2700chess; it is the only source that intentionally uses Residential proxy.

Need help? Open the Actor Issues tab with the run ID, input, filters, and relevant log lines.

FAQ

Which rating sources are supported? FIDE official rating downloads, Chess.com public API, Lichess public API, and optional 2700chess live ratings.

Does it always find Chess.com and Lichess accounts? No. There is no universal mapping between FIDE IDs and online usernames. The actor uses confirmed seed mappings for major players and fuzzy matching for leaderboard entries.

Can I look up one player? Yes. Set mode to player and provide fideId or playerName. fideId is recommended when you have it.

Can I get rapid or blitz FIDE lists? Yes. Set timeControl to rapid or blitz. Chess.com and Lichess enrichment can still include several online time controls.

Can I append output to an existing dataset? Yes. Pass datasetId to write rows to another dataset as well as the default run dataset. Pass runId to label rows from a parent workflow.

Is scraping chess ratings legal? The actor reads public rating lists and public profile/API data. Review source terms and your intended use case before republishing or commercializing derived data.

What are the limitations of Chess Ratings Aggregator?

• Online account matching is best for well-known players and can be missing for others.
• timeControl: all currently uses classical for FIDE player selection, while online sources may still return several time controls.
• 2700chess is optional, slower, and may fail if the site blocks browser automation.
• FIDE list downloads can change format or availability, which may require parser updates.
• Rating values are point-in-time snapshots from public sources, not official historical records.