Welcome to Chess.com Python Client Documentation!

Description

A Python client for Chess.com API which provides public data from the Chess.com website.

Indices and tables

Installation

The package requires Python 3.8 or higher.

Install from PyPI pip install chess.com

Retrieving Data

Using client instance

from chessdotcom import ChessDotComClient

client = ChessDotComClient(user_agent = "My Python Application...")

response = client.get_player_profile("fabianocaruana")

response.player.name # 'Fabiano Caruana'
response.player.title # 'GM'
response.player.last_online_datetime # datetime.datetime(2024, 10, 25, 20, 8, 28)
response.player.joined_datetime # datetime.datetime(2013, 3, 17, 15, 14, 32)
# See readthedocs for full documentation of responses

# or access the source
response.json['player']['name'] # 'Fabiano Caruana'

Using functions

from chessdotcom import get_player_profile, Client

Client.request_config["headers"]["User-Agent"] = (
   "My Python Application. "
   "Contact me at email@example.com"
)
response = get_player_profile("fabianocaruana")

Asynchronous

from chessdotcom import ChessDotComClient

client = ChessDotComClient(user_agent = "My Python Application...", aio = True)

usernames = ["fabianocaruana", "GMHikaruOnTwitch", "MagnusCarlsen", "GarryKasparov"]

cors = [client.get_player_profile(name) for name in usernames]

async def gather_cors(cors):
   return await asyncio.gather(*cors)

responses = asyncio.run(gather_cors(cors))

Managing Rate Limit

Every function accepts a tts parameter which controls the number of seconds the Client will wait before making the request. This is useful if running a lot of coroutines at once.

cors = [get_player_profile(name, tts = i / 10) for i, name in enumerate(usernames)]

The second method is to adjust the rate_limit_handler attribute of the Client object.

from chessdotcom import RateLimitHandler

client = ChessDotComClient(
   rate_limit_handler = RateLimitHandler(tts = 4,retries = 2)
)

If the initial request gets rate limited the client will automatically retry the request 2 more times with an interval of 4 seconds.

API Reference

Client

Player Data

Clubs

Tournaments

Team Matches

Countries

Daily Puzzle

Streamers

Leaderboards