Docs
Open Lodol
DocumentationIntegrationsAPI

Chess.com

App · Gaming · 16 actions

Access public Chess.com data through the keyless PubAPI: player profiles and stats, games and PGN archives, clubs, tournaments, titled players, leaderboards, streamers, and the daily puzzle. No account or API key required.

Actions

ActionWhat it does
Get club membersList a club's members, grouped by how recently they were active (weekly, monthly, and all-time).
Get club profileRetrieve a club's public details: name, member count, average rating, and admins.
Get country playersList the usernames of recently active Chess.com players who identify with a given country.
Get country profileLook up a country's Chess.com profile by ISO code.
Get current daily gamesList the player's Daily (correspondence) games that are currently in progress.
Get daily puzzleFetch the current Daily Puzzle, or a random puzzle from the archive when Random is enabled.
Get leaderboardsRetrieve the top-50 leaderboards across every category (daily, live rapid/blitz/bullet, tactics, and more).
Get monthly gamesRetrieve every finished game a player completed in a given month, including PGN, ratings, and results.
Get player clubsList the Chess.com clubs a player belongs to.
Get player profileLook up a Chess.com member's public profile: name, title, country, follower count, and account status.
Get player statsRetrieve a player's rating, best rating, and win/loss/draw record across each game type (rapid, blitz, bullet, daily, tactics, and puzzle rush).
Get player tournamentsList the tournaments a player has joined, grouped into finished, in-progress, and registered.
Get streamersList Chess.com streamers along with their live status and streaming-platform links.
Get titled playersList the usernames of every player holding a given chess title (for example, GM or WIM).
Get tournamentRetrieve a tournament's details, settings, standings, and rounds.
List monthly game archivesGet the list of monthly archive URLs available for a player.

Get club members

List a club's members, grouped by how recently they were active (weekly, monthly, and all-time).

Inputs

Club URL IDclub_idtextRequired
The club's URL ID, the slug at the end of its chess.com/club/ address (for example, san-francisco-mechanics-uscl). The full club URL works too, such as the url Get player clubs returns.

Outputs

membersobject
Each member appears in one list, by how recently they were active in the club.
Example output
{
  "members": {
    "all_time": [
      {
        "joined": 1500000000,
        "username": "player_three"
      }
    ],
    "monthly": [
      {
        "joined": 1700000000,
        "username": "player_two"
      }
    ],
    "weekly": [
      {
        "joined": 1710000000,
        "username": "player_one"
      }
    ]
  }
}

Get club profile

Retrieve a club's public details: name, member count, average rating, and admins.

Inputs

Club URL IDclub_idtextRequired
The club's URL ID, the slug at the end of its chess.com/club/ address (for example, san-francisco-mechanics-uscl). The full club URL works too, such as the url Get player clubs returns.

Outputs

clubobject
admin lists the admins' profile URLs; created and last_activity are Unix timestamps in seconds.
Example output
{
  "club": {
    "@id": "https://api.chess.com/pub/club/chess-com-developer-community",
    "average_daily_rating": 1300,
    "club_id": 57796,
    "country": "https://api.chess.com/pub/country/XX",
    "created": 1400000000,
    "description": "For developers building on the Chess.com API.",
    "icon": "https://images.chesscomfiles.com/uploads/club/icon.png",
    "join_request": "https://www.chess.com/club/chess-com-developer-community/join",
    "last_activity": 1717000000,
    "members_count": 5200,
    "name": "Chess.com Developer Community",
    "url": "https://www.chess.com/club/chess-com-developer-community",
    "visibility": "public"
  }
}

Get country players

List the usernames of recently active Chess.com players who identify with a given country. Chess.com caps the list at 10,000, so it isn't a full roster.

Inputs

Country ISO codeiso_codetextRequired
The 2-letter country code (for example, US, GB, or IN), or a country URL such as a player profile's country. Chess.com also uses XE for England, XS for Scotland, XW for Wales, and XX for International.

Outputs

playersobject
Example output
{
  "players": {
    "players": [
      "hikaru",
      "sample_player_2",
      "sample_player_3"
    ]
  }
}

Get country profile

Look up a country's Chess.com profile by ISO code.

Inputs

Country ISO codeiso_codetextRequired
The 2-letter country code (for example, US, GB, or IN), or a country URL such as a player profile's country. Chess.com also uses XE for England, XS for Scotland, XW for Wales, and XX for International.

Outputs

countryobject
Example output
{
  "country": {
    "@id": "https://api.chess.com/pub/country/US",
    "code": "US",
    "name": "United States"
  }
}

Get current daily games

List the player's Daily (correspondence) games that are currently in progress.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

gamesobject
Example output
{
  "games": {
    "games": [
      {
        "black": "https://api.chess.com/pub/player/magnuscarlsen",
        "fen": "r1bqkbnr/pppp1ppp/2n5/...",
        "last_activity": 1717000000,
        "move_by": 1717100000,
        "pgn": "[Event \"Let's Play!\"]\\n...",
        "rated": true,
        "time_control": "1/86400",
        "turn": "black",
        "url": "https://www.chess.com/game/daily/123456789",
        "white": "https://api.chess.com/pub/player/hikaru"
      }
    ]
  }
}

Get daily puzzle

Fetch the current Daily Puzzle, or a random puzzle from the archive when Random is enabled.

Inputs

Randomrandomtrue/false
Set to true to fetch a random puzzle instead of today's Daily Puzzle.Default: false.

Outputs

puzzleobject
publish_time is a Unix timestamp in seconds.
Example output
{
  "puzzle": {
    "fen": "6k1/5ppp/8/8/8/8/5PPP/4R1K1 w - - 0 1",
    "image": "https://www.chess.com/dynboard?fen=...",
    "pgn": "[Event \"Daily Puzzle\"]\\n...",
    "publish_time": 1717000000,
    "title": "Mate in Two",
    "url": "https://www.chess.com/forum/view/daily-puzzles/example"
  }
}

Get leaderboards

Retrieve the top-50 leaderboards across every category (daily, live rapid/blitz/bullet, tactics, and more).

Inputs

None.

Outputs

leaderboardsobject
Each board lists its top 50 players, best first.
Example output
{
  "leaderboards": {
    "daily": [],
    "live_blitz": [
      {
        "@id": "https://api.chess.com/pub/player/hikaru",
        "player_id": 15448422,
        "rank": 1,
        "score": 3312,
        "url": "https://www.chess.com/member/Hikaru",
        "username": "hikaru"
      }
    ],
    "live_bullet": [],
    "live_rapid": [],
    "tactics": []
  }
}

Get monthly games

Retrieve every finished game a player completed in a given month, including PGN, ratings, and results.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.
YearyearnumberRequired
The 4-digit year of the archive (for example, 2024).From 2007 to 2100.
MonthmonthnumberRequired
The month number, 1 (January) through 12 (December).From 1 to 12.

Outputs

gamesobject
Example output
{
  "games": {
    "games": [
      {
        "black": {
          "rating": 2755,
          "result": "checkmated",
          "username": "opponent"
        },
        "eco": "https://www.chess.com/openings/Sicilian-Defense",
        "end_time": 1704067200,
        "pgn": "[Event \"Live Chess\"]\\n...",
        "rated": true,
        "rules": "chess",
        "time_class": "rapid",
        "time_control": "600",
        "url": "https://www.chess.com/game/live/987654321",
        "white": {
          "rating": 2801,
          "result": "win",
          "username": "hikaru"
        }
      }
    ]
  }
}

Get player clubs

List the Chess.com clubs a player belongs to.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

clubsobject
Example output
{
  "clubs": {
    "clubs": [
      {
        "@id": "https://www.chess.com/club/chess-com-developer-community",
        "icon": "https://images.chesscomfiles.com/uploads/club/icon.png",
        "joined": 1500000000,
        "last_activity": 1717000000,
        "name": "Chess.com Developer Community",
        "url": "https://www.chess.com/club/chess-com-developer-community"
      }
    ]
  }
}

Get player profile

Look up a Chess.com member's public profile: name, title, country, follower count, and account status.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

profileobject
country is the URL of the player's country profile; joined and last_online are Unix timestamps in seconds.
Example output
{
  "profile": {
    "@id": "https://api.chess.com/pub/player/hikaru",
    "country": "https://api.chess.com/pub/country/US",
    "followers": 1129950,
    "is_streamer": true,
    "joined": 1389043258,
    "last_online": 1717000000,
    "location": "Sunrise, FL",
    "name": "Hikaru Nakamura",
    "player_id": 15448422,
    "status": "premium",
    "title": "GM",
    "url": "https://www.chess.com/member/Hikaru",
    "username": "hikaru",
    "verified": false
  }
}

Get player stats

Retrieve a player's rating, best rating, and win/loss/draw record across each game type (rapid, blitz, bullet, daily, tactics, and puzzle rush).

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

statsobject
One entry per game type the player has played; a type they haven't played is absent.
Example output
{
  "stats": {
    "chess_blitz": {
      "last": {
        "date": 1717000000,
        "rating": 3201,
        "rd": 27
      },
      "record": {
        "draw": 2500,
        "loss": 4210,
        "win": 20345
      }
    },
    "chess_bullet": {
      "last": {
        "date": 1717000000,
        "rating": 3312,
        "rd": 22
      },
      "record": {
        "draw": 1500,
        "loss": 8123,
        "win": 40012
      }
    },
    "chess_rapid": {
      "best": {
        "date": 1651000000,
        "rating": 2909
      },
      "last": {
        "date": 1717000000,
        "rating": 2789,
        "rd": 45
      },
      "record": {
        "draw": 180,
        "loss": 210,
        "win": 1234
      }
    }
  }
}

Get player tournaments

List the tournaments a player has joined, grouped into finished, in-progress, and registered.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

tournamentsobject
Each entry's url can be passed as the Tournament URL ID of Get tournament.
Example output
{
  "tournaments": {
    "finished": [
      {
        "@id": "https://api.chess.com/pub/tournament/example",
        "draws": 1,
        "losses": 1,
        "placement": 2,
        "points_awarded": 7,
        "status": "finished",
        "total_players": 24,
        "url": "https://www.chess.com/tournament/live/example",
        "wins": 3
      }
    ],
    "in_progress": [],
    "registered": []
  }
}

Get streamers

List Chess.com streamers along with their live status and streaming-platform links.

Inputs

None.

Outputs

streamersobject
Example output
{
  "streamers": {
    "streamers": [
      {
        "avatar": "https://images.chesscomfiles.com/uploads/v1/user/avatar.png",
        "is_community_streamer": true,
        "is_live": true,
        "twitch_url": "https://twitch.tv/gmhikaru",
        "url": "https://www.chess.com/member/Hikaru",
        "username": "hikaru"
      }
    ]
  }
}

Get titled players

List the usernames of every player holding a given chess title (for example, GM or WIM).

Inputs

TitletitletextRequired
The title abbreviation: GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, or WCM.One of: GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM.

Outputs

playersobject
Example output
{
  "players": {
    "players": [
      "hikaru",
      "magnuscarlsen",
      "fabianocaruana",
      "gothamchess"
    ]
  }
}

Get tournament

Retrieve a tournament's details, settings, standings, and rounds.

Inputs

Tournament URL IDtournament_idtextRequired
The tournament's URL ID, the slug at the end of its chess.com/tournament/ address. The full tournament URL works too, such as the url Get player tournaments returns.

Outputs

tournamentobject
settings holds the format (type, rules, time_class, time_control, total_rounds, and so on); start_time and finish_time are Unix timestamps in seconds.
Example output
{
  "tournament": {
    "@id": "https://api.chess.com/pub/tournament/monthly-blitz-championship",
    "name": "Monthly Blitz Championship",
    "players": [
      {
        "status": "winner",
        "username": "winner"
      },
      {
        "status": "eliminated",
        "username": "runner_up"
      }
    ],
    "rounds": [
      "https://api.chess.com/pub/tournament/monthly-blitz-championship/1"
    ],
    "settings": {
      "rules": "chess",
      "time_class": "blitz",
      "time_control": "180",
      "total_rounds": 9,
      "type": "swiss"
    },
    "start_time": 1704067200,
    "status": "finished",
    "url": "https://www.chess.com/tournament/live/monthly-blitz-championship"
  }
}

List monthly game archives

Get the list of monthly archive URLs available for a player. Each URL points to that month's finished games.

Inputs

UsernameusernametextRequired
The player's Chess.com username (for example, hikaru). A player URL works too, such as a leaderboard entry's url or a game's white or black player.

Outputs

archivesobject
Example output
{
  "archives": {
    "archives": [
      "https://api.chess.com/pub/player/hikaru/games/2024/01",
      "https://api.chess.com/pub/player/hikaru/games/2024/02",
      "https://api.chess.com/pub/player/hikaru/games/2024/03"
    ]
  }
}

CheapShark

Previous Page

Chinese Text Project

Next Page

On this page

ActionsGet club membersGet club profileGet country playersGet country profileGet current daily gamesGet daily puzzleGet leaderboardsGet monthly gamesGet player clubsGet player profileGet player statsGet player tournamentsGet streamersGet titled playersGet tournamentList monthly game archives