sportsball

A library for pulling in and normalising sports stats.

sportsball

Dependencies 🌐

Python 3.11.6:

Raison D'être 💭

sportsball aims to be a library for pulling in historical information about previous sporting games in a standardised fashion for easy data processing. The models it uses are designed to be used for many different types of sports.

The supported leagues are:

🏉 AFL
🏉 AFLW
🎾 ATP
⚽ BUNDESLIGA
⚽ EPL
⚽ FIFA
🐎 HKJC
🏏 IPL
⚽ LALIGA
⚾ MLB
🏀 NBA
🏀 NCAAB
🏀 NCAABW
🏈 NCAAF
🏈 NFL
🏒 NHL
🏀 WNBA
🎾 WTA

Architecture 📐

sportsball is an object orientated library. The entities are organised like so:

Game: A game within a season.
- Team: The team within the game. Note that in games with individual players a team exists as a wrapper.
  - Player: A player within the team.
    - Address: The address information of a players birth.
    - Owner: The owner of the player.
    - Venue: The college of the player.
  - Odds: The odds for the team to win the game.
    - Bookie: The bookie publishing the odds.
  - News: News about the team the day before the game.
  - Social: Social posts from the team the day before the game.
  - Coach: A coach for the team.
- Venue: The venue the game was played in.
  - Address: The address information of a venue.
    - Weather: The weather at the address.
- Dividend: The dividends the game pays out.
- Umpire: The umpires adjudicating the game.

Caching

This library uses very aggressive caching due to the large data requirements. If the requests are about a recent game (generally in the last 7 days) the caching is bypassed. The caching is as follows:

A joblib disk cache that caches calls to pydantic model creation functions. This changes on every version update to keep the models in sync. This is the fastest cache.
A requests cache backed by sqlite that caches requests forever.
An attempt to find the response is made to the wayback machine, and used if found.

It's very recommended that the user uses proxies defined in the PROXIES environment variable. The more proxies the easier it is to collect data.

Installation 📥

This is a python package hosted on pypi, so to install simply run the following command:

pip install sportsball

or install using this local repository:

python setup.py install --old-and-unmanageable

Usage example 👀

There are many different ways of using sportsball, but we generally recommend the CLI.

CLI

To fetch a dataframe containing information about a league, you can use the following CLI:

sportsball --league=nfl -

The final argument denotes the file to write to, in this case - is stdout.

Python

To pull a dataframe containing all the information for a particular league, the following example can be used:

from sportsball import sportsball as spb

ball = spb.SportsBall()
league = ball.league(spb.League.AFL)
df = league.to_frame()

This results in a dataframe where each game is represented by all its features.

Environment

If you wish to use the providers that require API keys, you can create a .env file with the following variables inside it:

GOOGLE_API_KEY=APIKEY
GRIBSTREAM_API_KEY=APIKEY
X_API_KEY=APIKEY
X_API_SECRET_KEY=APISECRETKEY
X_ACCESS_TOKEN=ACCESSTOKEN
X_ACCESS_TOKEN_SECRET=ACCESSTOKENSECRET
PROXIES=CSVPROXIESLIST

License 📝

The project is available under the MIT License.

Metadata

Release files for sportsball 0.34.148

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sportsball 0.34.148
File	Size	Uploaded	Provenance
sportsball-0.34.148.tar.gz	746.9 kB	Nov 13, 2025	Without provenance	Details

Release files / sportsball-0.34.148.tar.gz

Download URL	sportsball-0.34.148.tar.gz
Size	746.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`eac2ffa9580dd09f78e5492b7679838d374c4204823cea544ebec585ae163de2`
BLAKE2b-256 checksum How to use checksums	`6f628c6b2f8e23dae26e0de35ae4fb67bde40f7137bfca6e73d84f4d95566bc5`
Upload date	Nov 13, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.11.6`

Security for sportsball 0.34.148

Report project as malware

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.