chess-extractor 0.2.0

FIDE rating and game data extractor

Chess Extractor

A Python-based data extraction tool that retrieves FIDE rating history and individual game data (available from April 2008 onwards), merging them into structured datasets for statistical and performance analysis.

What is this for?

This tool allows you to build structured datasets from official FIDE data, enabling:

• Player performance analysis
• Rating progression tracking
• Statistical research on chess results

Data Coverage

Game-level data is only available from April 2008 onwards due to FIDE endpoint limitations.

Earlier periods are not available through the FIDE endpoint used for game extraction.

Requirements

• Python 3.9+
• Internet connection (FIDE scraping)

Limitations

• Only FIDE data available from official endpoints
• Game data starts from April 2008
• Requires internet connection

Features

Data extraction

• Extract complete monthly rating history from FIDE
• Retrieve all rated games for each rating period
• Detect opponent, rating, result and color (white/black)

Data processing

• Merge game data with player rating at the time
• Filter games by date range (--date-from, --date-to)

Interface

• Command-line interface (CLI) with positional arguments
• CLI tool: fide-tools fetch and fide-tools analyze

Output & storage

• Export structured datasets (.tsv / .csv)
• Local caching is optional and must be explicitly enabled (--cache)
• Installable command-line tool (fide-tools) via pip

Example output

Example extracted game dataset:

federation	opponent	o_rating	color	result	month	p_rating	k_chg
AZE	Mamedyarov, Shakhriyar	2760	Black	1.00	2008-04	2765	5.40
UKR	Eljanov, Pavel	2692	White	1.00	2008-04	2765	4.40
ENG	Adams, Michael	2726	Black	0.50	2008-04	2765	-0.10
ARM	Aronian, Levon	2739	White	0.50	2008-04	2765	0.10
UKR	Ivanchuk, Vassily	2751	Black	0.50	2008-04	2765	0.30

Installation

pip install chess-extractor

Or install locally (development mode)

pip install -e .

Commands

fetch

Extract FIDE rating history and game data for a player.

Arguments

• id (required)
  FIDE player ID (numeric identifier)

Options

• --date-from YYYY-MM — Start date filter (inclusive)
• --date-to YYYY-MM — End date filter (inclusive)
• --cache — Enable local caching of FIDE requests
• --export FILE — Export results to a TSV file

Syntax

fide-tools fetch <id> [--date-from YYYY-MM] [--date-to YYYY-MM] [--cache] [--export FILE]

Examples

Basic

fide-tools fetch 1503014

Advanced

fide-tools fetch 1503014 --date-from 2018-01 --date-to 2025-12 --export Carlsen.tsv --cache

Download sample dataset: Carlsen.tsv

---

analyze

Analyze extracted FIDE game dataset.

Options

• --id FIDE_ID — Fetch and analyze directly from FIDE

  • --performance — Compute FIDE performance rating

  • --elo-change — Compare expected rating impact (FIDE K-factor sum) vs observed rating change

  • --elo-diff-range — Filter games by opponent Elo difference

    • --elo-diff-lower INT — Lower bound
    • --elo-diff-upper INT — Upper bound

  • --date-from YYYY-MM — Start date filter (inclusive)

  • --date-to YYYY-MM — End date filter (inclusive)

  • --cache — Enable caching (only if using --id)

• --file FILE — Analyze local TSV file

  • (WIP: planned for offline analysis mode)

Syntax

fide-tools analyze (--id <id> | --file <file>) [options]

Note: You must provide either --id (live FIDE data) or --file (local dataset). They are mutually exclusive.

Examples

Basic

fide-tools analyze --id 1503014 --performance

Advanced

fide-tools analyze --id 1503014 --performance --elo-diff-range --elo-diff-lower -150 --elo-diff-upper 150 --cache

Troubleshooting

If you get empty results:

• Check your FIDE ID is valid
• Ensure the player has games after 2008-04
• Try without --date-from / --date-to

How it works

1. Scrape rating history from FIDE profile
2. Iterate through each rating period
3. Retrieve all games for each month
   • Note: Game-level data is only available from April 2008 onwards
   • Optionally filter games by date range before processing
4. Merge games with player rating
5. Export structured dataset

Possible Analysis

• Rating progression over time
• Winrate vs opponent rating
• Performance with White vs Black
• Average opponent strength
• Rating gain per tournament

Technical Notes

• Uses BeautifulSoup for HTML parsing
• Requests for HTTP calls
• FIDE endpoints used:
  • /a_indv_calculations.php
  • /profile/{id}
• Game data endpoint coverage begins in April 2008
• Handles inconsistent HTML tables
• Filters non-game rows (headers, summaries)
• Detects color via span classes (white_note / black_note)

Future Improvements

Performance & internal improvements

• Add cache expiration system (TTL-based caching)
• Investigate FIDE rate limits before enabling concurrency
• Parallelize monthly game fetching to reduce execution time (currently processed sequentially)

Data & export features

• Export directly to Excel (.xlsx)

User features

• Improve CLI UX (filters, validation, better date range handling)
• Visualization (matplotlib / seaborn)
• Multi-player comparison
• Web dashboard (Streamlit)

Distribution & packaging

• Package distribution via PyPI
• Windows executable (.exe via PyInstaller)

License

MIT License