Lichess Player, Game & Tournament Scraper

Scrape player profiles, full game histories (with PGN, clocks, and opening analysis), arena and Swiss tournament listings, and rating time-series from Lichess — the world's largest free, open-source chess server. No API key required.

What It Does

This actor connects directly to the Lichess REST API and returns structured data across four modes:

Mode	What You Get
player	Profile data: ratings (bullet/blitz/rapid/classical/correspondence/puzzle), game counts, play time, country, patron status
games	Full game history: PGN, moves in UCI notation, clocks, opening ECO + name, player ratings, variant, speed
tournaments	Active arena and Swiss tournaments: clock controls, variant, player count, winner, start time
rating_history	Rating time-series: full per-performance-category rating history as a JSON array

Why Lichess

Lichess publishes a fully open, anonymous-accessible API with no rate-key requirement and NDJSON streaming for bulk game downloads. It is the canonical open data source for chess research — powering cheat-detection models, opening-theory analysis, and academic chess datasets. Over 5 billion games are available.

Input

Field	Type	Description
mode	string (required)	player, games, tournaments, or rating_history
usernames	string[]	One or more Lichess usernames (required for player, games, rating_history modes)
maxItems	integer	Max records to return per username. Default: 10
rated	boolean	Games mode: return only rated games
perfType	string	Games mode: filter by speed/variant (e.g. blitz, rapid, chess960)

Example Input — Player Profiles

{
  "mode": "player",
  "usernames": ["thibault", "DrNykterstein", "Hikaru"],
  "maxItems": 10
}

Example Input — Game History

{
  "mode": "games",
  "usernames": ["DrNykterstein"],
  "maxItems": 50,
  "rated": true,
  "perfType": "blitz"
}

Example Input — Tournaments

{
  "mode": "tournaments",
  "maxItems": 20
}

Output

Each record has a record_type field indicating its type: player, game, tournament, or rating_history.

Player Record

{
  "record_type": "player",
  "username": "DrNykterstein",
  "title": "GM",
  "rating_bullet": 3288,
  "rating_blitz": 3212,
  "rating_rapid": 3001,
  "games_count": 85000,
  "wins": 52000,
  "losses": 18000,
  "draws": 15000,
  "country": "NO",
  "patron": false,
  "verified": false
}

Game Record

{
  "record_type": "game",
  "game_id": "q7ZvsdUF",
  "rated": true,
  "variant": "standard",
  "speed": "blitz",
  "status": "resign",
  "winner": "white",
  "white_user": "DrNykterstein",
  "white_rating": 3190,
  "black_user": "Hikaru",
  "black_rating": 3120,
  "opening_eco": "B12",
  "opening_name": "Caro-Kann Defense",
  "moves": "e2e4 c7c6 d2d4 ...",
  "pgn": "1. e4 c6 2. d4 ...",
  "clock_initial": 180,
  "clock_increment": 0
}

Tournament Record

{
  "record_type": "tournament",
  "tournament_id": "mfZoVuwM",
  "tournament_name": "Hourly Blitz Arena",
  "tournament_system": "arena",
  "tournament_clock": "3+0",
  "tournament_variant": "blitz",
  "tournament_rated": true,
  "tournament_nb_players": 217,
  "tournament_winner": "penguingim1"
}

Use Cases

• Chess research: Download game databases for machine learning, opening theory, or statistical analysis
• Player tracking: Monitor rating trends and performance across time controls
• Tournament analytics: Track active tournaments, player counts, and results
• Comparative analysis: Benchmark player profiles across the Lichess community

Rate Limits

Lichess rate-limits anonymous API access. This actor automatically handles 429 responses with exponential backoff and adds a 500ms courtesy delay between requests.

Notes

• No API key or Lichess account required for public data
• Games returned newest-first
• rating_history records contain the full time-series as a JSON string
• The moves field uses UCI notation (e.g. e2e4); PGN uses standard algebraic notation

---

Further reading: Streaming Charts and Box Office Data: Spotify, Netflix, Maoyan & More