Docs

Usage basics

Creating a pychasing.Client

The pychasing Client is where all https://ballchasing.com API endpoints are exposed.

import pychasing

pychasing_client = pychasing.Client(
    "<your_token>", # your API token
    True, # whether or not to automatically rate limit
    pychasing.types.PatreonTier.Regular # your Patreon tier; Regular = no tier
)

pychasing.Client responses

When one of the API functions are used, it will return a pychasing.client.Response object. This object contains various values from the API call:

res = pychasing_client.get_replay("<replay_id>")

print(res.response)
>>> <class 'requests.Response'>
print(res.operation)
>>> "get_replay"
print(res.value)
>>> {...} # if an abnormal status code is returned, i.e. 409, an appropriate error will be raised, i.e. pychasing.exceptions.DuplicateReplay

Each function's value attribute of its returned pychasing.client.Response object, assuming no error is encountered, returns either a dict, bytes, or None. For example, get_replay returns a dict, while download_replay returns bytes. The return type of each function's Response.value is noted within its docstring.

API functionality

Universal status codes

# status code 401 (raises MissingApiKey)
{
    "chat": {
        "Imp": "Sorry",
        "YOU": "Centering"
    },
    "error": "missing API key"
}


# status code 429 (raises RateLimitExceeded)
None


# status code 500 (raises APIUnvailable)
{
    "error": "ballchasing.com fault. reason here"
}

Ping

Example

res = pychasing_client.ping()

Response value

# last updated: 19 September 2022

# status code 200
{
    "ball": "is life",
    "boost": "over ball",
    "chaser": True,
    "chat": {
        "Iceman": "No Problem.",
        "YOU": "My Fault."
    },
    "name": "Can't Fly",
    "steam_id": str, # the token holder's steam ID
    "type": "regular" | "diamond" | "champion" | "gc"
}

Upload replay

Example

with open("my_replay_file.replay", "rb") as replay:
    res = pychasing_client.upload_replay(
        replay,
        pychasing.types.Visibility.PRIVATE
    )

Response value

# last updated: 19 September 2022

# status code 201
{
    "id": str, # the ID of the uploaded replay
    "location": str # a link (https://ballchasing.com/replay/...) to the replay
}

# status code 400
{
    "error": str # fault on your end
}

# status code 409
{
    "id": str, # the ID of the uploaded replay
    "location": str, # a link (https://ballchasing.com/replay/...) to the replay
    "error": "duplicate replay",
    "chat": {
        "Poncho": "Whew.",
        "YOU": "Oops"
    }
}

# status code 500
{
    "error": str # fault on ballchasing's end
}