chessdotcom

README

ChessDotCom

ChessDotCom is a minimal wrapper for the official Chess.com REST API. Key features:

• All responses are fully typed.
• Logical beautification of field names. (e.g. @id becomes ID)
• Built-in handling of PGN data types.
• Internal request management to prevent API throttling.
• ZERO external dependencies!

Overview

This package is designed to be incredibly lightweight and simple to use, mirroring the offering of the official Chess.com API.

Installation

ChessDotCom has been developed and fully tested with Go version 1.19. While it will likely work with other versions, it is not recomended.

Install the package:

go get github.com/A-ndy-git/chessdotcom

Import into your project:

import (
  "github.com/A-ndy-git/chessdotcom"
)

Usage

You probably shouldn't. ChessDotCom is primarily a personal education project. Nevertheless, its simple enough to provide value if you need it.

Create a new client instance, and you are done! Simples!

client := chessdotcom.New()

// Client is instantiated and ready to be used. E.g.
res, err := client.PlayerProfile("magnuscarlsen")
...

Documentation

Automatically created GoDoc docs are available here. High level methods are listed below.

Player

• Profile - Get additional details about a player in a game

res, err := client.PlayerProfile("erik")
if err != nil {
  // handle error
}

// res ->
  {
    "Avatar": "https://images.chesscomfiles.com/uploads/v1/user/41.5434c4ff.200x200o.5b102889d835.jpeg",
    "PlayerId": 41,
    "ID": "https://api.chess.com/pub/player/erik",
    "URL": "https://www.chess.com/member/erik",
    "Name": "Erik",
    "Username": "erik",
    "Followers": 4340,
    "Country": "https://api.chess.com/pub/country/US",
    "Location": "Bay Area, CA",
    "LastOnline": 1669316678,
    "Joined": 1178556600,
    "Status": "staff",
    "IsStreamer": false,
    "Verified": true
  }

---

• Stats - Get ratings, win/loss, and other stats about a player's game play, tactics, lessons and Puzzle Rush score.

client.PlayerStats("magnuscarlsen")

---

• Games - Array of Daily Chess games that a player is currently playing.

client.PlayerGames("magnuscarlsen")

---

• Game Archive - Array of monthly archives available for this player.

client.PlayerGameArchive("magnuscarlsen")

---

• Games to Move - Array of Daily Chess games where it is the player's turn to act.

client.PlayerGamesToMove("magnuscarlsen")

---

• Archive PGN - standard multi-game format PGN containing all games for a month.

client.PlayerAchivePGN("magnuscarlsen", "2022", "01")

---

• Game Monthly Archive - Array of Live and Daily Chess games that a player has finished.

client.PlayerGameMonthlyArchive("magnuscarlsen", "2022", "01")

---

• Clubs - List of clubs the player is a member of, with joined date and last activity date.

client.PlayerClubs("magnuscarlsen")

---

• Tournaments - List of tournaments the player is registered, is attending or has attended in the past.

client.PlayerTournaments("magnuscarlsen")

---

• Titled Players - List of titled-player usernames.

client.PlayerTitledPlayers()

---

Club

Tournament

Team Match

Country

Daily Puzzle

Point System Config

Documentation

Index

• Variables
• type Best
• type ChessDaily
• type ChessRapid
• type ChessRating
• type Client
  • func New() *Client
  • func (c *Client) PlayerClubs(username string) ([]PlayerClub, error)
  • func (c *Client) PlayerGameArchivePGN(username, year, month string) (string, error)
  • func (c *Client) PlayerGameArchives(username string) ([]string, error)
  • func (c *Client) PlayerGameMonthlyArchive(username, year, month string) ([]PlayerGame, error)
  • func (c *Client) PlayerGames(username string) ([]PlayerGames, error)
  • func (c *Client) PlayerGamesToMove(username string) ([]PlayerGamesToMove, error)
  • func (c *Client) PlayerProfile(username string) (PlayerProfile, error)
  • func (c *Client) PlayerStats(username string) (PlayerStats, error)
  • func (c *Client) PlayerTournaments(username string) (PlayerTournamentsResponse, error)
  • func (c *Client) TitledPlayers() ([]string, error)
• type Last
• type Player
• type PlayerClub
• type PlayerGame
• type PlayerGames
• type PlayerGamesToMove
• type PlayerProfile
• type PlayerStats
• type PlayerTournament
• type PlayerTournamentsResponse
• type PuzzleRushBest
• type Record
• type Tactics
• type Tournament

Variables

var (
	ErrApiUnavailable = errors.New("api currently unavailable")
	ErrRateLimit      = errors.New("rate limited by api")
	ErrTimeout        = errors.New("request timed out")
	ErrGeneric        = errors.New("internal server error")
)

Types

type Best

type Best struct {
	Rating int64         `json:"rating"`
	Date   time.Duration `json:"date"`
	Game   string        `json:"game"`
}

type ChessDaily

type ChessDaily struct {
	Last       Last       `json:"last"`
	Best       Best       `json:"best"`
	Record     Record     `json:"record"`
	Tournament Tournament `json:"tournament"`
}

type ChessRapid

type ChessRapid struct {
	Last   Last   `json:"last"`
	Best   Best   `json:"best"`
	Record Record `json:"record"`
}

type ChessRating

type ChessRating struct {
	Rating int64         `json:"rating"`
	Date   time.Duration `json:"date"`
}

type Client

type Client struct {
	*http.Client
}

func New

func New() *Client

Creates a new ChessDotCom client instance with default opts.

func (*Client) PlayerClubs

func (c *Client) PlayerClubs(username string) ([]PlayerClub, error)

Returns an array of clubs a player is a member of, with joined date and last activity date.

func (*Client) PlayerGameArchivePGN

func (c *Client) PlayerGameArchivePGN(username, year, month string) (string, error)

Returns standard multi-game format PGN containing all games for a month for a player.

func (*Client) PlayerGameArchives

func (c *Client) PlayerGameArchives(username string) ([]string, error)

Returns an array of monthly game archives available for a player.

func (*Client) PlayerGameMonthlyArchive

func (c *Client) PlayerGameMonthlyArchive(username, year, month string) ([]PlayerGame, error)

Returns an array of live and daily chess games that a player has finished.

func (*Client) PlayerGames

func (c *Client) PlayerGames(username string) ([]PlayerGames, error)

Returns an array of daily chess games that a player is currently playing.

func (*Client) PlayerGamesToMove

func (c *Client) PlayerGamesToMove(username string) ([]PlayerGamesToMove, error)

Returns an array of daily chess games where it is a players turn to act.

func (*Client) PlayerProfile

func (c *Client) PlayerProfile(username string) (PlayerProfile, error)

Returns details of an existing player.

func (*Client) PlayerStats

func (c *Client) PlayerStats(username string) (PlayerStats, error)

Returns ratings, win/loss, and other stats about a players game play, tactics, lessons and puzzle rush score.

func (*Client) PlayerTournaments

func (c *Client) PlayerTournaments(username string) (PlayerTournamentsResponse, error)

Returns an array of tournaments a player is registered, is attending or has attended in the past.

func (*Client) TitledPlayers

func (c *Client) TitledPlayers() ([]string, error)

Returns an array of titled-player usernames.

type Last

type Last struct {
	Rating int64         `json:"rating"`
	Date   time.Duration `json:"date"`
	Rd     int64         `json:"rd"`
}

type Player

type Player struct {
	Rating   int64  `json:"url"`
	Result   string `json:"result"`
	ID       string `json:"@id"`
	Username string `json:"username"`
	UUID     string `json:"uuid"`
}

type PlayerClub

type PlayerClub struct {
	ID           string        `json:"@id"`
	Name         string        `json:"name"`
	LastActivity time.Duration `json:"last_activity"`
	Icon         string        `json:"icon"`
	URL          string        `json:"url"`
	Joined       time.Duration `json:"joined"`
}

type PlayerGame

type PlayerGame struct {
	URL          string        `json:"url"`
	PGN          string        `json:"pgn"`
	TimeControl  string        `json:"time_control"`
	EndTime      time.Duration `json:"end_time"`
	Rated        bool          `json:"rated"`
	TCN          string        `json:"tcn"`
	UUID         string        `json:"uuid"`
	InitialSetup string        `json:"initial_setup"`
	FEN          string        `json:"fen"`
	StartTime    time.Duration `json:"start_time"`
	TimeClass    string        `json:"time_class"`
	Rules        string        `json:"rules"`
	White        Player        `json:"white"`
	Black        Player        `json:"black"`
}

type PlayerGames

type PlayerGames struct {
	URL          string        `json:"url"`
	MoveBy       int64         `json:"move_by"`
	PGN          string        `json:"pgn"`
	TimeControl  string        `json:"time_control"`
	LastActivity time.Duration `json:"last_activity"`
	Rated        bool          `json:"rated"`
	Turn         string        `json:"turn"`
	FEN          string        `json:"fen"`
	StartTime    time.Duration `json:"start_time"`
	TimeClass    string        `json:"time_class"`
	Rules        string        `json:"rules"`
	White        string        `json:"white"`
	Black        string        `json:"black"`
}

type PlayerGamesToMove

type PlayerGamesToMove struct {
	URL          string        `json:"url"`
	MoveBy       int64         `json:"move_by"`
	LastActivity time.Duration `json:"last_activity"`
}

type PlayerProfile

type PlayerProfile struct {
	Avatar     string        `json:"avatar"`
	PlayerId   int64         `json:"player_id"`
	ID         string        `json:"id"`
	URL        string        `json:"url"`
	Name       string        `json:"name"`
	Username   string        `json:"username"`
	Followers  int64         `json:"followers"`
	Country    string        `json:"country"`
	Location   string        `json:"location"`
	LastOnline time.Duration `json:"last_online"`
	Joined     time.Duration `json:"joined"`
	Status     string        `json:"status"`
	IsStreamer bool          `json:"is_streamer"`
	Verified   bool          `json:"verified"`
}

type PlayerStats

type PlayerStats struct {
	ChessDaily    ChessDaily     `json:"chess_daily"`
	Chess960Daily ChessDaily     `json:"chess960_daily"`
	ChessRapid    ChessRapid     `json:"chess_rapid"`
	ChessBullet   ChessRapid     `json:"chess_bullet"`
	ChessBlitz    ChessRapid     `json:"chess_blitz"`
	Fide          int64          `json:"fide"`
	Tactics       Tactics        `json:"tactics"`
	PuzzleRush    PuzzleRushBest `json:"puzzle_rush"`
}

type PlayerTournament

type PlayerTournament struct {
	URL           string `json:"url"`
	ID            string `json:"@id"`
	Wins          int    `json:"wins"`
	Losses        int    `json:"losses"`
	Draws         int    `json:"draws"`
	PointsAwarded int    `json:"points_awarded"`
	Placement     int    `json:"placement"`
	Status        string `json:"status"`
	TotalPlayers  int    `json:"total_players"`
}

type PlayerTournamentsResponse

type PlayerTournamentsResponse struct {
	Finished   []PlayerTournament `json:"finished"`
	InProgress []PlayerTournament `json:"in_progress"`
	Registered []PlayerTournament `json:"registered"`
}

type PuzzleRushBest

type PuzzleRushBest struct {
	TotalAttempts int64 `json:"total_attempts"`
	Score         int64 `json:"score"`
}

type Record

type Record struct {
	Win            int64         `json:"win"`
	Loss           int64         `json:"loss"`
	Draw           int64         `json:"draw"`
	TimePerMove    time.Duration `json:"time_per_move"`
	TimeoutPercent int           `json:"timeout_percent"`
}

type Tactics

type Tactics struct {
	Highest ChessRating `json:"highest"`
	Lowest  ChessRating `json:"lowest"`
}

type Tournament

type Tournament struct {
	Points        int64 `json:"points"`
	Withdraw      int64 `json:"withdraw"`
	Count         int64 `json:"count"`
	HighestFinish int64 `json:"highest_finish"`
}