# Chess.com

> 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.

App · Gaming · 16 actions. Web page: https://docs.lodol.com/docs/integrations/chess-com

## Actions

### Get club members

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

**Inputs**

- Club URL ID (`club_id`, text, required): 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**

- `members` (object): Each member appears in one list, by how recently they were active in the club.

**Example output**

```json
{
  "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 ID (`club_id`, text, required): 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**

- `club` (object): admin lists the admins' profile URLs; created and last_activity are Unix timestamps in seconds.

**Example output**

```json
{
  "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 code (`iso_code`, text, required): 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**

- `players` (object)

**Example output**

```json
{
  "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 code (`iso_code`, text, required): 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**

- `country` (object)

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `games` (object)

**Example output**

```json
{
  "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**

- Random (`random`, true/false): Set to true to fetch a random puzzle instead of today's Daily Puzzle. Default: `false`.

**Outputs**

- `puzzle` (object): publish_time is a Unix timestamp in seconds.

**Example output**

```json
{
  "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**

- `leaderboards` (object): Each board lists its top 50 players, best first.

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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.
- Year (`year`, number, required): The 4-digit year of the archive (for example, 2024). From 2007 to 2100.
- Month (`month`, number, required): The month number, 1 (January) through 12 (December). From 1 to 12.

**Outputs**

- `games` (object)

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `clubs` (object)

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `profile` (object): country is the URL of the player's country profile; joined and last_online are Unix timestamps in seconds.

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `stats` (object): One entry per game type the player has played; a type they haven't played is absent.

**Example output**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `tournaments` (object): Each entry's url can be passed as the Tournament URL ID of Get tournament.

**Example output**

```json
{
  "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**

- `streamers` (object)

**Example output**

```json
{
  "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**

- Title (`title`, text, required): 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**

- `players` (object)

**Example output**

```json
{
  "players": {
    "players": [
      "hikaru",
      "magnuscarlsen",
      "fabianocaruana",
      "gothamchess"
    ]
  }
}
```

### Get tournament

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

**Inputs**

- Tournament URL ID (`tournament_id`, text, required): 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**

- `tournament` (object): 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**

```json
{
  "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**

- Username (`username`, text, required): 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**

- `archives` (object)

**Example output**

```json
{
  "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"
    ]
  }
}
```