Chess API

Chess.com and Lichess players, ratings, games with PGN and leaderboards in one JSON format.

The API.SH Chess API covers Chess.com and Lichess through one set of routes. Look up a player's profile and ratings, download their games with full PGN, opening and result, read the leaderboard for any time control, and list every titled player on Chess.com. Pick the site with the site parameter.

Get a free API key Try it in the playground

4 endpoints
from $1 / 1,000 calls
1,000 free credits / month
failed calls free

Chess.com or lichess player profile and ratings

GET https://api.api.sh/chess/v1/player

{ "success": true }

1 credit · $1 per 1,000 calls

What you can build with the Chess API

Player scouting and prep

Pull a rival's profile, ratings and recent games, filtered by color, result or time control, to study their openings.

/player /games

Opening and game analysis

Collect games with PGN, ECO code and opening name, plus accuracies on Chess.com, to feed your own analysis tools or databases.

/games

Rating trackers and dashboards

Show current, best and record ratings for every time control, with a leaderboard next to it.

/player /leaderboard

Titled player lists

List all Chess.com GMs, IMs, FMs and other titled players to build club, coach or media lists.

/titled

Chess apps and AI agents

Let a bot or assistant answer how a player is rated, how they have been doing, or who leads blitz.

/player /leaderboard /games

Chess data you get

Field names from real responses. Numbers come parsed, URLs absolute, dates in ISO 8601.

Chess API endpoints and prices

Every Chess endpoint costs 1 credit per call: credits are $1 per 1,000 on a monthly plan, $2 pay-as-you-go. Pricing

Profiles and accounts1

Chess.com or lichess player profile and ratings

/chess/v1/player

$1 · $2 PAYG

1 credit

More data3

A player's games with PGN /chess/v1/games	$1 · $2 PAYG 1 credit
Chess.com or lichess leaderboard /chess/v1/leaderboard	$1 · $2 PAYG 1 credit
Chess.com titled players /chess/v1/titled	$1 · $2 PAYG 1 credit

Call the Chess API

Chess.com or lichess player profile and ratings: GET https://api.api.sh/chess/v1/player

curl "https://api.api.sh/chess/v1/player?username=hikaru" \
  -H "x-api-key: $APISH_KEY"

import os, requests

res = requests.get(
    "https://api.api.sh/chess/v1/player",
    params={"username": "hikaru"},
    headers={"x-api-key": os.environ["APISH_KEY"]},
    timeout=120,
)
res.raise_for_status()
data = res.json()

const url = new URL("https://api.api.sh/chess/v1/player");
url.searchParams.set("username", "hikaru");

const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

# Google Sheets (API.SH add-on)
=APISH("/chess/v1/player", "username", "hikaru")

# Zapier, Make, n8n (verified node): pick the API.SH app,
# choose "Chess" and "Chess.com or lichess player profile and ratings".

# AI agents (Claude, ChatGPT, Cursor): add the
# API.SH MCP server https://api.sh/mcp

Create a free accountConfirm your email and get 1,000 free credits every month. No card needed.
Create an API keyOne key works for all 483 platforms.
Send the requestJSON back in one call. Add output=csv or output=ndjson for files.

Why API.SH for Chess data

Public data only: no Chess login, cookies or account needed
One key and one response shape for Chess and 482 other platforms
Built and maintained by API.SH, not third-party publishers
Pay per call; errors on our side cost nothing
Live status for every endpoint

API.SH vs the official Chess API

Both sites publish their own APIs: Chess.com has a read-only public API (PubAPI) for profiles, stats, games, clubs and leaderboards, and Lichess has a documented API of its own. API.SH puts both behind one key and one JSON shape, so the same code works for either site. It does not run engine analysis such as Stockfish.

Skip stitching two chess APIs together or buying an Apify scraper: API.SH returns Chess.com and Lichess data from one key at a fixed price per call.

Chess API questions

What chess data can I get?+

Player profiles and ratings (/chess/v1/player), a player's games with PGN (/chess/v1/games), leaderboards by time control (/chess/v1/leaderboard) and Chess.com titled players (/chess/v1/titled), for Chess.com or Lichess.

How much does the Chess API cost?+

Every Chess endpoint costs 1 credit per call. On a monthly plan 1,000 credits cost $1 (Starter is $50/month for 50,000 credits). Pay-as-you-go is $2 per 1,000 credits, with top-ups from $15 that never expire.

Is there a free trial?+

Yes. Every account gets 1,000 free credits every month. That is 1,000 calls to /chess/v1/games at 1 credit each.

Is there a free Chess.com or Lichess API?+

Yes, both sites publish their own: Chess.com has a read-only public API and Lichess documents an open API. API.SH is an alternative when you want both sites in one JSON format with a single key and filters such as color, result, time_class and opponent.

Do I need a Chess.com or Lichess account or login?+

No. API.SH reads public Chess.com or Lichess pages only. No endpoint uses a login, cookies or anyone's account.

Can I use it from Python?+

Yes. Call any route over HTTPS with your key from requests, or use the Python SDK. A call like /chess/v1/games with a username and site=lichess returns JSON you can load straight into pandas.

Does it include engine analysis or Stockfish?+

No. It returns public profile, rating and game data, including accuracies on Chess.com games that were analysed. For engine evaluation, run Stockfish on the PGN it returns.

How do I get started?+

1. Sign up at api.sh. 2. Copy your API key. 3. Call /chess/v1/player with a username and site=chesscom or site=lichess, then /chess/v1/games for their games. Request examples and every parameter are in the docs at https://api.sh/docs. You can also use the JS or Python SDK, Google Sheets, Zapier, Make, n8n or the MCP server at https://api.sh/mcp.