API Methods

The module lichess.api provides thin wrappers around the lichess API.

In addition to the API parameters, each function takes optional format, auth, and client arguments.

Endpoints that return collections (like user_games) stream the results by returning a generator.

lichess.api.user(username, **kwargs)

Wrapper for the GET /api/user/<username> endpoint.

>>> user = lichess.api.user('thibault')
>>> print(user.get('perfs', {}).get('blitz', {}).get('rating'))
1617

lichess.api.users_by_team(team, **kwargs)

Wrapper for the GET /api/team/{name}/users endpoint. Returns a generator that streams the user data.

>>> users = lichess.api.users_by_team('coders')
>>> ratings = [u.get('perfs', {}).get('blitz', {}).get('rating') for u in users]
>>> print(ratings)
[1349, 1609, ...]

lichess.api.users_by_ids(ids, **kwargs)

Wrapper for the POST /api/users endpoint. Returns a generator that splits the IDs into multiple requests as needed.

Note: Use users_status when possible, since it is cheaper and not rate-limited.

>>> users = lichess.api.users_by_ids(['thibault', 'cyanfish'])
>>> ratings = [u.get('perfs', {}).get('blitz', {}).get('rating') for u in users]
>>> print(ratings)
[1617, 1948]

lichess.api.users_status(ids, **kwargs)

Wrapper for the GET /api/users/status endpoint. Returns a generator that makes requests for additional pages as needed.

Note: This endpoint is cheap and not rate-limited. Use it instead of users_by_ids when possible.

>>> users = lichess.api.users_status(['thibault', 'cyanfish'])
>>> online_count = len([u for u in users if u.get('online')])
>>> print(online_count)
1

lichess.api.user_activity(username, **kwargs)

Wrapper for the GET /api/user/<username>/activity endpoint.

lichess.api.game(game_id, **kwargs)

Wrapper for the GET /api/game/{id} endpoint.

By default, returns a dict representing a JSON game object. Use format=PGN for a PGN string or format=PYCHESS for a python-chess game object.

>>> game = lichess.api.game('Qa7FJNk2')
>>> print(game['moves'])
e4 e5 Nf3 Nc6 Bc4 Qf6 d3 h6 ...

>>> from lichess.format import PGN, PYCHESS
>>> pgn = lichess.api.game('Qa7FJNk2', format=PGN)
>>> print(pgn)
[Event "Casual rapid game"]
...

>>> game_obj = lichess.api.game('Qa7FJNk2', format=PYCHESS)
>>> print(game_obj.end().board())
. . k . R b r .
. p p r . N p .
p . . . . . . p
. . . . . . . .
. . . p . . . .
P . . P . . . P
. P P . . P P .
. . K R . . . .

lichess.api.games_by_ids(ids, **kwargs)

Wrapper for the POST /games/export/_ids endpoint. Returns a generator that splits the IDs into multiple requests as needed.

lichess.api.user_games(username, **kwargs)

Wrapper for the GET /api/user/<username>/games endpoint.

By default, returns a generator that streams game objects. Use format=PGN for a generator of game PGNs, format=SINGLE_PGN for a single PGN string, or format=PYCHESS for a generator of python-chess game objects.

>>> games = lichess.api.user_games('cyanfish', max=50, perfType='blitz')
>>> print(next(games)['moves'])
e4 e5 Nf3 Nc6 Bc4 Qf6 d3 h6 ...

>>> from lichess.format import PGN, SINGLE_PGN, PYCHESS
>>> pgns = lichess.api.user_games('cyanfish', max=50, format=PGN)
>>> print(next(pgns))
[Event "Casual rapid game"]
...

>>> pgn = lichess.api.user_games('cyanfish', max=50, format=SINGLE_PGN)
>>> print(pgn)
[Event "Casual rapid game"]
...

>>> game_objs = lichess.api.user_games('cyanfish', max=50, format=PYCHESS)
>>> print(next(game_objs).end().board())
. . k . R b r .
. p p r . N p .
p . . . . . . p
. . . . . . . .
. . . p . . . .
P . . P . . . P
. P P . . P P .
. . K R . . . .

lichess.api.tournaments(**kwargs)

Wrapper for the GET /api/tournament endpoint.

lichess.api.tournament(tournament_id, **kwargs)

Wrapper for the GET /api/tournament/<tournamentId> endpoint.

lichess.api.tournament_standings(tournament_id, **kwargs)

Wrapper for the GET /api/tournament/<tournamentId> endpoint. Returns a generator that makes requests for additional pages as needed.

lichess.api.tv_channels(**kwargs)

Wrapper for the GET /tv/channels endpoint.