code Chesscom API

How to access Chesscom programmatically to retrieve JSON and PGN content.

The PubAPI is a read-only REST service that returns public Chess.com data as JSON-LD.
You cannot send moves or other commands through this API.

1. General Use & Features

1.1 Cache Invalidation

Endpoints refresh at most once every 12 hours unless otherwise noted.

1.2 Not-Yet-Guaranteed Current Data

Approx 3% of players still use the legacy “v2” site; actions there may delay data freshness. Mobile apps are unaffected.

1.3 English-Only Text

All human-readable strings (e.g. result codes) are returned in English.

1.4 Rate Limiting

  • Serial requests are unlimited.
  • Parallel requests may receive 429 Too Many Requests.
  • Abuse can trigger an IP/UA block. Include a contact e-mail in your UA string so Chess.com can reach you.

1.5 How to Call the API

Any HTTP-capable client (browser, curl, Postman, Insomnia, etc.).

curl -v https://api.chess.com/pub/player/hikaru

Postman/Insomnia collection: collection-dev.json

1.6 Timestamps

All times are Unix seconds since 1970-01-01 UTC.

1.7 HTTP Responses

CodeMeaning
200Enjoy your JSON
301Permanent redirect – update your stored URL
304Cached copy is still current
404Malformed URL or data not found
410Resource will never exist – stop requesting
429Rate limit exceeded

1.8 JSON-LD

Every endpoint sends a Link: header to its JSON-LD context; the body remains plain JSON.

1.9 JSONP Support

Append ?callback=YourFunction.

https://api.chess.com/pub/player/erik?callback=myJavascriptFunction

1.10 Caching Headers

Responses include ETag, Last-Modified, and Cache-Control: max-age=….

1.11 HTTP Compression & HTTP/2

Responses > ≈200 B are gzipped when Accept-Encoding: gzip is present; HTTP/2 is supported.

2. Endpoints

2.1 Player Data

2.1.1 Player Profile

URL: https://api.chess.com/pub/player/{username}

{
  "@id": "URL",
  "url": "URL",
  "username": "string",
  "player_id": 41,
  "title": "string",
  "status": "basic | premium | mod | staff | closed | closed:fair_play_violations",
  "name": "string",
  "avatar": "URL",
  "location": "string",
  "country": "URL",
  "joined": 1178556600,
  "last_online": 1500661803,
  "followers": 17,
  "is_streamer": true,
  "twitch_url": "URL",
  "fide": 2500
}

2.1.2 Titled Players

URL: https://api.chess.com/pub/titled/{GM|WGM|IM|…}

{
  "players": [ "Hikaru", "Carlsen", … ]
}

2.1.3 Player Stats

URL: https://api.chess.com/pub/player/{username}/stats

{
  "chess_daily": { … },
  "chess960_daily": { … },
  "chess_blitz": { … },
  "tactics": { … },
  "lessons": { … },
  "puzzle_rush": { … }
}
{
  "last": { "date": 1509709165, "rating": 1642, "rd": 58 },
  "best": { "date": 1256228875, "rating": 2065, "game": "URL" },
  "record": {
    "win": 177, "loss": 124, "draw": 21,
    "time_per_move": 18799,
    "timeout_percent": 9.99
  },
  "tournament": {
    "count": 20, "withdraw": 1,
    "points": 39, "highest_finish": 1
  }
}

2.1.4 Player Online Status

URL: https://api.chess.com/pub/player/{username}/is-online

{ "online": true }

2.2 Player Games

All game lists share:

{
  "games": [ /* Game objects */ ]
}

2.2.1 Current Daily Chess

URL: https://api.chess.com/pub/player/{username}/games

{
  "white": "URL",
  "black": "URL",
  "url": "URL",
  "fen": "string",
  "pgn": "string",
  "turn": "black",
  "move_by": 1501765498,
  "draw_offer": "black",
  "last_activity": 1509810789,
  "start_time": 1254438881,
  "time_control": "1/86400",
  "time_class": "daily",
  "rules": "chess",
  "tournament": "URL",
  "match": "URL"
}

2.2.2 To-Move Daily Chess

URL: https://api.chess.com/pub/player/{username}/games/to-move

{
  "games": [
    {
      "url": "string",
      "move_by": 1254438881,
      "draw_offer": true,
      "last_activity": 1509810789
    }
  ]
}

2.2.3 List of Monthly Archives

URL: https://api.chess.com/pub/player/{username}/games/archives

{
  "archives": [
    "https://api.chess.com/pub/player/erik/games/2025/01",
    …
  ]
}

2.2.4 Complete Monthly Archive

URL: https://api.chess.com/pub/player/{username}/games/{YYYY}/{MM}

{
  "white": {
    "username": "string",
    "rating": 1492,
    "result": "win",
    "@id": "URL"
  },
  "black": {
    "username": "string",
    "rating": 1942,
    "result": "lose",
    "@id": "URL"
  },
  "accuracies": {
    "white": 94.7,
    "black": 88.3
  },
  "url": "URL",
  "fen": "string",
  "pgn": "string",
  "start_time": 1254438881,
  "end_time": 1254670734,
  "time_control": "300+5",
  "rules": "chess960",
  "eco": "URL",
  "tournament": "URL",
  "match": "URL"
}

2.2.5 Live Archive by Time Control

URL: https://api.chess.com/pub/player/{username}/games/live/{BASETIME}/{INCREMENT}

{
  "games": [
    {
      "url": "string",
      "pgn": "string",
      "time_control": "300+2",
      "end_time": 1277170171,
      "rated": true,
      "accuracies": {
        "white": 86.4,
        "black": 89.1
      },
      "fen": "string",
      "time_class": "blitz",
      "rules": "chess",
      "white": {
        "username": "string",
        "rating": 1661,
        "result": "win",
        "@id": "URL",
        "uuid": "fe696c00-fcba-11db-8029-000000000000"
      },
      "black": {
        "username": "string",
        "rating": 1577,
        "result": "loss",
        "@id": "URL",
        "uuid": "d65c8c3a-5313-11df-805e-000000000000"
      },
      "eco": "URL"
    }
  ]
}

2.2.6 Multi-Game PGN Download

URL: https://api.chess.com/pub/player/{username}/games/{YYYY}/{MM}/pgn

Returns a standard PGN file with headers. Headers:

  • Content-Type: application/x-chess-pgn
  • Content-Disposition: attachment; filename="ChessCom_{username}_{YYYYMM}.pgn"

2.3 Player Participation

2.3.1 Player’s Clubs

URL: https://api.chess.com/pub/player/{username}/clubs

{
  "clubs": [
    {
      "@id": "URL",
      "name": "Club Name",
      "last_activity": 1600000000,
      "icon": "URL",
      "url": "URL",
      "joined": 1580000000
    }
  ]
}

2.3.2 Player Matches

URL: https://api.chess.com/pub/player/{username}/matches

{
  "finished": [
    {
      "name": "Match Name",
      "url": "URL",
      "@id": "URL",
      "club": "URL",
      "results": {
        "played_as_white": "win",
        "played_as_black": "loss"
      },
      "board": "URL"
    }
  ],
  "in_progress": [
    {
      "name": "Match Name",
      "url": "URL",
      "@id": "URL",
      "club": "URL",
      "board": "URL"
    }
  ],
  "registered": [
    {
      "name": "Match Name",
      "url": "URL",
      "@id": "URL",
      "club": "URL"
    }
  ]
}

2.3.3 Player Tournaments

URL: https://api.chess.com/pub/player/{username}/tournaments

{
  "finished": [
    {
      "url": "URL",
      "@id": "URL",
      "wins": 3,
      "losses": 5,
      "draws": 0,
      "points_awarded": 0,
      "placement": 4,
      "status": "eliminated",
      "total_players": 5
    }
  ],
  "in_progress": [
    {
      "url": "URL",
      "@id": "URL",
      "status": "in_progress"
    }
  ],
  "registered": [
    {
      "url": "URL",
      "@id": "URL",
      "status": "invited"
    }
  ]
}

2.4 Clubs

2.4.1 Club Profile

URL: https://api.chess.com/pub/club/{url-ID}

{
  "@id": "URL",
  "name": "string",
  "club_id": 57796,
  "icon": "URL",
  "country": "URL",
  "average_daily_rating": 1376,
  "members_count": 54,
  "created": 1178556600,
  "last_activity": 1500661803,
  "visibility": "public",
  "join_request": "URL",
  "admin": [
    "URL", …
  ],
  "description": "string"
}

2.4.2 Club Members

URL: https://api.chess.com/pub/club/{url-ID}/members

{
  "weekly": [
    { "username": "string", "joined": 1600000000 }
  ],
  "monthly": [
    { "username": "string", "joined": 1590000000 }
  ],
  "all_time": [
    { "username": "string", "joined": 1500000000 }
  ]
}

2.4.3 Club Matches

URL: https://api.chess.com/pub/club/{url-ID}/matches

{
  "finished": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "result": "win",
      "start_time": 1305324926,
      "time_class": "daily"
    }
  ],
  "in_progress": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "start_time": 1305324926,
      "time_class": "daily"
    }
  ],
  "registered": [
    {
      "name": "match name",
      "@id": "URL",
      "opponent": "URL",
      "time_class": "daily"
    }
  ]
}

2.5 Tournaments

2.5.1 Tournament Profile

URL: https://api.chess.com/pub/tournament/{url-ID}

{
  "name": "string",
  "url": "URL",
  "description": "string",
  "creator": "username",
  "status": "finished",
  "finish_time": 1251846528,
  "settings": {
    "type": "round_robin",
    "rules": "string",
    "time_class": "daily",
    "time_control": "1/259200",
    "is_rated": true,
    "is_official": false,
    "is_invite_only": false,
    "initial_group_size": 5,
    "user_advance_count": 1,
    "use_tiebreak": true,
    "allow_vacation": false,
    "winner_places": 1,
    "registered_user_count": 5,
    "games_per_opponent": 2,
    "total_rounds": 1,
    "concurrent_games_per_opponent": 1
  },
  "players": [
    { "username": "username", "status": "eliminated" }
  ],
  "rounds": [
    "URL", …
  ]
}

2.5.2 Tournament Round

URL: https://api.chess.com/pub/tournament/{url-ID}/{round}

{
  "groups": [ "URL", … ],
  "players": [
    { "username": "username", "is_advancing": false }
  ]
}

2.5.3 Tournament Round Group

URL: https://api.chess.com/pub/tournament/{url-ID}/{round}/{group}

{
  "fair_play_removals": [ "username", … ],
  "games": [
    {
      "white": "URL",
      "black": "URL",
      "url": "URL",
      "fen": "string",
      "pgn": "string",
      "turn": "black",
      "move_by": 1501765498,
      "draw_offer": "black",
      "last_activity": 1509810789,
      "start_time": 1254438881,
      "time_control": "string",
      "time_class": "string",
      "rules": "string",
      "eco": "URL"
    }
  ],
  "players": [
    {
      "username": "username",
      "points": 2,
      "tie_break": 6,
      "is_advancing": false
    }
  ]
}

2.6 Team Matches

2.6.1 Daily Team Match Profile

URL: https://api.chess.com/pub/match/{ID}

{
  "name": "string",
  "url": "URL",
  "description": "string",
  "start_time": 1614000000,
  "settings": {
    "time_class": "daily",
    "time_control": "1/259200",
    "initial_setup": "startpos",
    "rules": "chess",
    "min_team_players": 4,
    "max_team_players": 8,
    "min_required_games": 10,
    "min_rating": 800,
    "max_rating": 2400,
    "autostart": true
  },
  "status": "registration",
  "boards": 0,
  "teams": {
    "team1": { /* … */ },
    "team2": { /* … */ }
  }
}

2.6.2 Daily Team Match Board

URL: https://api.chess.com/pub/match/{ID}/{board}

{
  "board_scores": {
    "player1": 0.5,
    "player2": 1.5
  },
  "games": [
    {
      "white": {
        "username": "player1",
        "rating": 1492,
        "result": "win",
        "@id": "URL",
        "team": "URL"
      },
      "black": {
        "username": "player2",
        "rating": 1540,
        "result": "checkmated",
        "@id": "URL",
        "team": "URL"
      },
      "accuracies": { "white": 92.3, "black": 85.0 },
      "url": "URL",
      "fen": "string",
      "pgn": "string",
      "start_time": 1620000000,
      "end_time": 1620500000,
      "time_control": "1/259200",
      "time_class": "daily",
      "rules": "chess",
      "eco": "URL",
      "match": "URL"
    }
  ]
}

2.6.3 Live Team Match Profile

URL: https://api.chess.com/pub/match/live/{ID}

{
  "@id": "URL",
  "name": "Friendly 5+2",
  "url": "URL",
  "start_time": 1579471260,
  "end_time": 1579472487,
  "status": "finished",
  "boards": 6,
  "settings": {
    "rules": "chess",
    "time_class": "blitz",
    "time_control": 300,
    "time_increment": 2,
    "min_team_players": 2,
    "autostart": false
  },
  "teams": {
    "team1": { /* … */ },
    "team2": { /* … */ }
  }
}

2.6.4 Live Team Match Board

URL: https://api.chess.com/pub/match/live/{ID}/{board}

{
  "board_scores": { "stompall": 1.5, "jydra21": 0.5 },
  "games": [
    {
      "url": "https://www.chess.com/live/game/4415534343",
      "pgn": "PGN of the game",
      "time_control": "300+2",
      "end_time": 1579471691,
      "rated": true,
      "fen": "r7/p4pN1/1pn4k/8/2bP3R/2P3R1/6PP/6K1 b - -",
      "time_class": "blitz",
      "rules": "chess",
      "white": {
        "rating": 1351,
        "result": "win",
        "@id": "URL",
        "username": "stompall"
      },
      "black": {
        "rating": 1458,
        "result": "checkmated",
        "@id": "URL",
        "username": "jydra21"
      },
      "eco": "URL"
    }
  ]
}

2.7 Countries

2.7.1 Country Profile

URL: https://api.chess.com/pub/country/{ISO2}

{
  "@id": "URL",
  "name": "Italy",
  "code": "IT"
}

2.7.2 Country Players

URL: https://api.chess.com/pub/country/{ISO2}/players

{
  "players": [ "PlayerA", "PlayerB", … ]
}

2.7.3 Country Clubs

URL: https://api.chess.com/pub/country/{ISO2}/clubs

{
  "clubs": [ "https://api.chess.com/pub/club/club-slug", … ]
}

2.8 Daily Puzzle API

2.8.1 Today’s Puzzle

URL: https://api.chess.com/pub/puzzle

{
  "title": "Puzzle Title",
  "url": "URL",
  "publish_time": 1513584000,
  "fen": "FEN",
  "pgn": "PGN",
  "image": "URL"
}

2.8.2 Random Past Puzzle

URL: https://api.chess.com/pub/puzzle/random

{
  "title": "Puzzle Title",
  "url": "URL",
  "publish_time": 1513584000,
  "fen": "FEN",
  "pgn": "PGN",
  "image": "URL"
}

2.9 Streamers

URL: https://api.chess.com/pub/streamers

{
  "streamers": [
    {
      "username": "string",
      "avatar": "URL",
      "twitch_url": "URL",
      "url": "https://www.chess.com/member/username"
    }
  ]
}

2.10 Leaderboards

URL: https://api.chess.com/pub/leaderboards

{
  "daily": [
    {
      "player_id": 12345678,
      "@id": "URL",
      "url": "URL",
      "username": "string",
      "score": 2900,
      "rank": 1
    },
    …
  ],
  "live_blitz": [ … ],
  "tactics": [ … ],
  "lessons": [ … ]
}

3. Game Result Codes

CodeDescription
winWin
checkmatedCheckmated
agreedDraw agreed
repetitionDraw by repetition
timeoutTimeout
resignedResigned
stalemateStalemate
loseLoss
insufficientInsufficient material
50moveDraw by 50-move rule
abandonedAbandoned
kingofthehillKing reached the hill
threecheckThree-check win
timevsinsufficientTimeout vs insufficient material draw
bughousepartnerloseBughouse partner lost

Last reviewed & updated: 2022-05-10  |  Comments  |  Revision history