https://github.com/purarue/chess_export
Export your chess.com/lichess.org games using their APIs
https://github.com/purarue/chess_export
chess chessdotcom lichess lichess-api pgn
Last synced: 6 months ago
JSON representation
Export your chess.com/lichess.org games using their APIs
- Host: GitHub
- URL: https://github.com/purarue/chess_export
- Owner: purarue
- License: mit
- Created: 2021-02-25T23:04:57.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-13T02:37:46.000Z (over 1 year ago)
- Last Synced: 2025-07-31T19:57:13.401Z (11 months ago)
- Topics: chess, chessdotcom, lichess, lichess-api, pgn
- Language: Python
- Homepage: https://pypi.org/project/chess-export/
- Size: 52.7 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# chess_export
[](https://pypi.python.org/pypi/chess_export) [](https://pypi.python.org/pypi/chess_export) [](http://makeapullrequest.com)
Export your (or someone else's) chess.com/lichess.org games using their APIs
- Chess.com requires no authentication, see their [public API docs](https://www.chess.com/news/view/published-data-api)
- Lichess requires you to create a token, you can do so by going [here](https://lichess.org/account/oauth/token/create?description=lichess+export) (this requires no extra scopes)
## Installation
Requires `python3.10+`
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 purarue >data.json
Requesting https://api.chess.com/pub/player/purarue/games/archives
Requesting https://api.chess.com/pub/player/purarue/games/2021/01
...
```
If you're getting 403 errors, you may have to supply a user agent with your email, see [this forum thread](https://www.chess.com/clubs/forum/view/error-403-in-member-profile)
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](https://lichess.org/account/oauth/token/create?description=lichess+export) (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 purarue > data.json
Requesting https://lichess.org/api/games/user/purarue?pgnInJson=true
```
### Example
The games are described in [`PGN`](https://en.wikipedia.org/wiki/Portable_Game_Notation) (which can be parsed using the [`chess`](https://python-chess.readthedocs.io/en/latest/pgn.html) package)
```
$ chess_export chessdotcom export purarue >data.json
Requesting https://api.chess.com/pub/player/purarue/games/archives
Requesting https://api.chess.com/pub/player/purarue/games/2021/01
Requesting https://api.chess.com/pub/player/purarue/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](chess_export/lichess/model.py) and [chessdotcom/model.py](chess_export/chessdotcom/model.py) files for reference
### Tests
```bash
git clone 'https://github.com/purarue/chess_export'
cd ./chess_export
pip install '.[testing]'
mypy ./chess_export
```