Title: Access to the 'Lichess' API
Version: 1.0.1
Description: Package that accesses the 'Lichess' API (https://lichess.org/api). Supports both authenticated and unauthenticated requests. Basic functionality for game and player analysis.
License: MIT + file LICENSE
URL: https://github.com/kylehamilton/horsey
BugReports: https://github.com/kylehamilton/horsey/issues
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: httr2, jsonlite, tibble, dplyr, stringr, cli, rlang
Suggests: spelling, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Language: en-US
NeedsCompilation: no
Packaged: 2026-01-16 22:32:05 UTC; kyleh
Author: W. Kyle Hamilton ORCID iD [aut, cre]
Maintainer: W. Kyle Hamilton <kyle.hamilton@gmail.com>
Repository: CRAN
Date/Publication: 2026-01-22 09:20:02 UTC

horsey: Access to the 'Lichess' API

Description

Package that accesses the 'Lichess' API (https://lichess.org/api). Supports both authenticated and unauthenticated requests. Basic functionality for game and player analysis.

Author(s)

Maintainer: W. Kyle Hamilton kyle.hamilton@gmail.com (ORCID)

See Also

Useful links:

Create a Lichess API client for analysis/export workflows

Description

horsey is designed for read-only access and data export. Provide a token for endpoints that require authentication. If token is NULL, client() will use Sys.getenv("LICHESS_TOKEN").

Usage

client(token = NULL, base_url = "https://lichess.org", quiet = FALSE)

Arguments

token

Bearer token (personal API token or OAuth access token). If NULL, uses Sys.getenv("LICHESS_TOKEN").

base_url

API base URL. Defaults to ⁠https://lichess.org⁠.

quiet

Suppress informational messages.

Value

An object of class horsey_client.

Export games for a player

Description

Downloads games from ⁠/api/games/user/{username}⁠ and requests NDJSON. Returns a tibble of commonly-used analysis fields, plus a raw list-column containing each full game object as returned by the API.

Usage

export_games(
  cl,
  username,
  max = 100,
  since = NULL,
  until = NULL,
  perfType = NULL,
  rated = NULL,
  opening = TRUE
)

Arguments

cl

A horsey_client.

username

Lichess username.

max

Maximum number of games to request (default 100).

since

Optional epoch milliseconds (inclusive).

until

Optional epoch milliseconds (exclusive).

perfType

Optional perf filter (e.g., "blitz", "rapid").

rated

Optional logical filter.

opening

If TRUE, ask Lichess to include opening info when available.

Value

A tibble with selected metadata columns and a raw list-column.

Summarize openings from exported games

Description

Counts openings from export_games() output. To include opening information, opening = TRUE in export_games().

Usage

opening_summary(games, top_n = 20)

Arguments

games

Tibble returned by export_games().

top_n

Number of top openings to return.

Details

Two columns are produced by export_games() when opening = TRUE:

opening_name

An opening name provided by Lichess (for example, "Sicilian Defense" or "Queen's Gambit Declined").

opening_eco

The ECO code associated with the opening (for example, "B20" or "D30"). ECO (Encyclopaedia of Chess Openings) codes are a standardized classification system for chess openings.

Value

A tibble of the most common openings with columns for the ECO code, opening name, and count of games.

Get a user's rating history

Description

Returns rating history for each game type (e.g., blitz, rapid).

Usage

rating_history(cl, username)

Arguments

cl

A horsey_client.

username

A Lichess username.

Value

A tibble with columns perf, rating, date.

Summarize results (W/L/D) for a player

Description

Produces win/loss/draw counts for a specified player

Usage

result_summary(games, player)

Arguments

games

Tibble returned by export_games().

player

Username (required for accurate W/L/D).

Value

A tibble with one row containing the player name plus totals for games, wins, losses, and draws.

Get a user's public profile

Description

Retrieves a public user profile from the Lichess API.

Usage

user(cl, username, tz = "UTC")

Arguments

cl

A horsey_client.

username

Lichess username.

tz

Time zone for the returned datetime fields. Defaults to "UTC".

Value

A tibble with selected fields, plus a raw list-column.

Get a user's activity feed

Description

Retrieves the activity feed for a user. This wrapper intentionally returns a minimal summary and includes the raw activity objects in a list-column.

Usage

user_activity(cl, username)

Arguments

cl

A horsey_client.

username

Lichess username.

Value

A tibble with one row per activity entry and a raw column.

Compute win rate from exported games

Description

Computes a win rate from the tibble returned by export_games().

Usage

winrate(games, player = NULL)

Arguments

games

Tibble returned by export_games().

player

Optional username to compute perspective-correct results. If NULL, uses winner only and treats non-win as non-win.

Value

Win rate.