lichess: a Python wrapper for the Lichess API

lichess is a Python library for interacting with the Lichess API and can be used to get profile data, game data, and much more.

Installation

You can install lichess on the Terminal (macOS/UNIX) or the Command Prompt (Windows) with:

pip install lichess

Alternatively, you can use Git to clone the repository from GitHub with:

git clone https://github.com/qe/lichess.git
cd lichess
pip install .

Or, if you already have it, upgrade to the latest version with:

pip install lichess -U

Usage

For the full documentation, please check the Lichess Python API Documentation.

Some methods, such as Client.get_email(), require authorization while others, such as Client.get_leaderboard(), do not require it. As a result, if you want to use a method/endpoint that does require authorization, you will need to generate a personal access token on Lichess. If you do so, this will be your API Key.

To determine whether or nor you need to generate a personal access token, check if the endpoint you are interested in using has a OAuth2 badge in the Lichess API Documentation.

Here is an example of using lichess without a personal access token:

import lichess

myclient = lichess.Client()

Here is an example of using lichess with a personal access token:

import lichess

API_KEY = "<YOUR API KEY GOES HERE>"
myclient = lichess.Client(token=API_KEY)

Quick Examples

The following are some examples of popular uses of this package:

Get the profile data of a user

import lichess

myclient = lichess.Client()
user = myclient.get_data("bmartin")

Get the rating history of a user

import lichess

myclient = lichess.Client()
history = myclient.get_rating_history("agadmator")

Get the list of users that are offline, online, and playing

import lichess

myclient = lichess.Client()
users = ["Oliver_Penrose", "bmartin", "ismodes", "penguingim1", "Zhigalko_Sergei"]
data = myclient.get_status(users)

offline = [i['name'] for i in data if 'online' not in i.keys()]
online = [i['name'] for i in data if 'online' in i.keys()]
playing = [i['name'] for i in data if 'playing' in i.keys()]

Download all the games of a user

import lichess

myclient = lichess.Client()
games = myclient.export_by_user("penguingim1")

with open("games.pgn", "w") as f:
    f.write(games)
f.close()

Get the list of all the members of a team

import lichess

API_KEY = "<YOUR API KEY GOES HERE>"
myclient = lichess.Client(token=API_KEY)
members = myclient.get_team_members("vu-chess-club")

Get the list of all the IDs of the puzzles you have failed

import lichess

API_KEY = "<YOUR API KEY GOES HERE>"
myclient = lichess.Client(token=API_KEY)
activity = myclient.get_puzzle_activity()
failed = [i['id'] for i in activity if not i['win']]

For more examples, check the examples directory in the source code.

Links

• Lichess Python API Documentation
• Lichess API Documentation
• Lichess Website