Python Ballchasing
An easy-to-use and comprehensive Python wrapper for the ballchasing.com API.
Installation
You can install the library from PyPI using pip:
pip install python-ballchasing
Authentication
Before you can use the library, you need an API authentication key from ballchasing.com.
- Log in to ballchasing.com.
- Navigate to the Upload tab.
- Create an API key and copy it.
Keep your API key secure and do not share it publicly.
API
For detailed information, please refer to the docs inside the code. For the most part it follows the API spec closely, but there are some differences.
The API is exposed via the BallchasingApi class.
Making the client:
from ballchasing import BallchasingApi
api = BallchasingApi("Your token here")
or equivalently
import ballchasing
api = ballchasing.Api("Your token here")
By default this will also ping the API to make sure it's working.
Some simple examples:
# Get lots of SSL replays
from ballchasing import Rank # there's also Playlist, Season, Map, and more
replays = api.get_replays(
min_rank=Rank.SUPERSONIC_LEGEND,
count=10_000 # The API limits you to 200 replays per request but the library handles this for you
)
for replay in replays: # (replays is an iterable so you don't need to wait for all the replays to be collected)
... # Do something with the replays
# Get a specific replay with more detail than the iterator (including stats!)
replay = api.get_replay("2627e02a-aa46-4e13-b66b-b76a32069a07")
# Get groups by the "RLCS Referee" account
groups = api.get_groups(creator="76561199225615730")
for group in groups:
# Download the group
api.download_group(
group_id=group["id"],
path="/path/to/destination/"
recursive=True, # To download all the replays and retain the group structure with subfolders
)
# Get replays from the group
replays = get_group_replays(
group_id=group["id"],
deep=True, # To get detailed replay info
)
for replay in replays:
api.download_replay(replay_id=replay["id"], path="/path/to/destination/") # You could also download like this
Additionally, there's the option to put responses (replays, groups) into typed objects for better type hinting and validation.
It also attempts to fill in missing variables not returned by ballchasing (e.g. if a team has 0 goals they won't have a "goal" entry in the response)
The classes can also be found under the typing folder and used as a reference for what the API returns.
# When creating the API, you can specify a default setting for typing (defaults to False)
api = ballchasing.Api("Your token here", typed=True)
# or you can specify it explicitly
replay = api.get_replay("2627e02a-aa46-4e13-b66b-b76a32069a07", typed=True)
print(replay.blue.players[0].name) # Example of easy attribute access
group = api.get_group("g2-vs-bds-hwbf2eyolb", typed=True)
print(group.players[0].name)
1 maintainer
Release files for python-ballchasing 0.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| python_ballchasing-0.5.1.tar.gz | 31.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| python_ballchasing-0.5.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 67.3 kB
Release files / python_ballchasing-0.5.1.tar.gz
| Download URL | python_ballchasing-0.5.1.tar.gz |
|---|---|
| Size | 31.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a0510ef1e094c0b715b287afacbed71e8f84e146531bc01b55c53be62d19077b
|
|
BLAKE2b-256 checksum How to use checksums |
6f6424a83fccd73f7df73d4d747f7c56f0f41eb246de59b9e0e4037c61fe42ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / python_ballchasing-0.5.1-py3-none-any.whl
| Download URL | python_ballchasing-0.5.1-py3-none-any.whl |
|---|---|
| Size | 36.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82bc3d409e7037b036185b3137d102a194d24893f8129ef8437355dbb90947ff
|
|
BLAKE2b-256 checksum How to use checksums |
537535dcd6c8925d15515847f1b0d0132d2d49d8cb32df09179c4512fc6e6423
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
