chess_export

Export your (or someone else's) chess.com/lichess.org games using their APIs

• Chess.com requires no authentication, see their public API docs
• Lichess requires you to create a token, you can do so by going here (this requires no extra scopes)

Installation

Requires python3.8+

To install with pip, run:

pip install chess-export

Usage

Each subcommand (chessdotcom/lichess) has an export and inspect command -- export prints data about your games as JSON, inspect reads that dumped info so you can use it in the REPL.

The inspect command just accepts the file as the first argument, like chess_export lichess inspect data.json or chess_export chessdotcom inspect data.json

chessdotcom export

The only required argument is your username, the API serves public data and has no serial rate limit

$ chess_export chessdotcom export seanbreckenridge >data.json
Requesting https://api.chess.com/pub/player/seanbreckenridge/games/archives
Requesting https://api.chess.com/pub/player/seanbreckenridge/games/2021/01
...

If you're getting 403 errors, you may have to supply a user agent with your email, see this forum thread

To do that, you can pass the --user-agent-email flag or set the CHESSDOTCOM_USER_AGENT_EMAIL environment variable.

lichess export

Requires your username and a token (this requires no extra scopes). The token can be provided with the --token flag or by setting the LICHESS_TOKEN environment variable.

$ chess_export lichess export seanbreckenridge > data.json
Requesting https://lichess.org/api/games/user/seanbreckenridge?pgnInJson=true

Example

The games are described in PGN (which can be parsed using the chess package)

$ chess_export chessdotcom export seanbreckenridge >data.json
Requesting https://api.chess.com/pub/player/seanbreckenridge/games/archives
Requesting https://api.chess.com/pub/player/seanbreckenridge/games/2021/01
Requesting https://api.chess.com/pub/player/seanbreckenridge/games/2021/02
$ chess_export chessdotcom inspect data.json

In [1]: import io, chess.pgn

In [2]: game = chess.pgn.read_game(io.StringIO(games[0].pgn))

In [3]: for move in game.mainline_moves():
   ...:     print(move)
   ...:
e2e4
e7e6
b1c3
d8f6
d2d3
f8c5
d3d4
c5d4
f2f3

The information returned by chess.com/lichess are slightly different, see the lichess/model.py and chessdotcom/model.py files for reference

Tests

git clone 'https://github.com/seanbreckenridge/chess_export'
cd ./chess_export
pip install '.[testing]'
mypy ./chess_export