How to Use the Chess.com API in Python

🧠 How to Use the Chess.com API in Python — With Headers & Real Examples♟️🐍

So what do you want to do with the Chess.com API?

You can pull user profiles, ratings, games, tournament participants, and more. The data is all public, and it's a great way to build analysis tools, or club automation systems.

⚠️ Why You Need Custom Headers

Before we jump into the code, here’s a critical tip:
Always include headers in your API requests.

Chess.com uses rate limiting and spam prevention. If you skip the headers, you’ll be Forbidden.

• 403 Forbidden (Access denied)

If do do to much to fast you will get.

• 429 Too Many Requests (You’ve hit the rate limit)

Adding a proper User-Agent with your app name and contact info tells their system:

“Hey, I’m not a bot. I’m a human using this responsibly. Here’s how to reach me.”

🧰 Setup: Define Your Custom Headers in Python

We'll use an Enum to organize different headers for different purposes. This is optional but clean and scalable:

from enum import Enum
import requests

# 🧠 Define headers for each type of API call
class Api_Headers(Enum):
    ACTIVE_PLAYERS = {
        "User-Agent": "GT-Active-Players-App/1.0 (Python 3.9.13) -- Finds daily players. (contact- BEST @YourUsername on Chess.com or LEAST RELIABLE dev@example.com)",
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive"
    }
    TOURNAMENT_PARTICIPANTS = {
        "User-Agent": "GT-Tournament-Participation-App/1.0 (Python 3.9.13) -- Gets tournament player list. (contact- BEST @YourUsername on Chess.com or LEAST RELIABLE dev@example.com)",
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive"
    }
    USER_INFO = {
        "User-Agent": "GT-User-Info-App/1.0 (Python 3.9.13) -- Gets user info. (contact- BEST @YourUsername on Chess.com or LEAST RELIABLE dev@example.com)",
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive"
    }

🧪 Example: Get the List of Players in a Tournament

Let’s say you want to get a list of usernames who joined a specific tournament.

📘 Endpoint:
https://api.chess.com/pub/tournament/{tournament-name}/players

Here’s a full Python function to do just that:

def get_tournament_usernames(tournament_name):
    """
    Queries the Chess.com public API to get the list of player usernames in a tournament.

    Parameters:
    tournament_name (str): The slug or URL-friendly name of the tournament
                           (e.g., 'gt-april-showers-knockout-1-1600').

    Returns:
    list: A list of usernames who are participants in the tournament.
    """

    # Build the full API URL using the tournament name
    url = f"https://api.chess.com/pub/tournament/{tournament_name}/players"

    # Make the GET request with headers to avoid rate-limiting or blocking
    response = requests.get(
        url,
        headers=Api_Headers.TOURNAMENT_PARTICIPANTS.value
    )

    # If the request fails (e.g., bad tournament or missing headers), print status
    if response.status_code != 200:
        print(f"⚠️ Failed to get players: HTTP {response.status_code}")
        return []

    # Convert the JSON API response into a Python dictionary
    data = response.json()

    # Extract the list of usernames from the response
    usernames = [
        player["username"]
        for player in data.get("players", [])
        if "username" in player
    ]

    return usernames

🧪 Try It Out:

players = get_tournament_usernames("gt-april-showers-knockout-1-1600")
print(players)

Output:

['ChessFan123', 'QueenCrusher', 'KnightRider89', ...]

✅ Summary

• Headers matter: use User-Agent to avoid getting blocked.

• The API is free and public — but you still need to be polite.

• The data you can grab is super useful for clubs, tournaments, analysis, and automation.

💬 Got questions? Want to explore more endpoints like user stats, game history, or leaderboards? Drop a comment in this thread.