5DollarFootballAPI — Python client
Official Python client for the 5DollarFootballAPI: football (soccer) fixtures, live scores, standings, statistics and odds — including full odds movement history and corner & card lines most football APIs don't carry.
- 15 endpoints, one method each — mirrors the API docs exactly
- Automatic retry on rate limits, honoring
Retry-After - Typed exceptions (
AuthenticationError,RateLimitError, ...) with the API's error code andrequest_id - Built-in pagination helper that walks
has_morepages for you - Python 3.8+, one dependency (
requests)
Also available for Node.js: npm install fivedollarfootball.
Install
pip install fivedollarfootball
Quickstart
Grab a free API key at 5dollarfootballapi.com — the free tier covers the top-5 European leagues, no credit card required.
from fivedollarfootball import Client
client = Client("fb_live_your_key")
# Today's fixtures (kickoff window defaults to today UTC)
for match in client.fixtures():
teams = match["teams"]
print(teams["home"]["name"], "vs", teams["away"]["name"], "-", match["status"])
# Live matches only
live = client.fixtures(status="live")
# One fixture with events and statistics included
fixture = client.fixture(1234567, include=["events", "stats"])
Odds and odds history
# Current prices for a fixture: 1x2, Asian handicap, goal line, corners, cards, BTTS
odds = client.fixture_odds(1234567, bookmakers=["bet365", "pinnacle"], market="1x2")
# Every recorded price movement for a market — the endpoint most APIs don't have
for tick in client.iter_all(client.odds_history, fixture_id=1234567, market="corner"):
print(tick)
# Which bookmakers are available on your plan
books = client.bookmakers()
Leagues, teams, standings
leagues = client.leagues(popular=True)
league_id = leagues[0]["id"]
# A league season's fixtures
finished = client.league_fixtures(league_id, status="finished")
# League table — also as corner or card standings
table = client.standings(league_id)
corner_table = client.standings(league_id, type="corner")
team_id = finished[0]["teams"]["home"]["id"]
team = client.team(team_id)
recent = client.team_fixtures(team_id, status="finished")
Pagination
Paginated methods return a Page (a plain list plus page, per_page, count, has_more). To walk every page:
for fixture in client.iter_all(client.fixtures, status="finished"):
...
Time windows
start_time / end_time accept unix seconds or datetime objects (naive datetimes are treated as UTC):
import datetime as dt
start = dt.datetime(2026, 8, 22, tzinfo=dt.timezone.utc)
weekend = client.fixtures(start_time=start, end_time=start + dt.timedelta(hours=24))
Errors and rate limits
from fivedollarfootball import APIError, RateLimitError
try:
client.fixture(999999999)
except RateLimitError as e:
print("try again in", e.retry_after, "seconds")
except APIError as e:
print(e.status_code, e.code, e.message, e.request_id)
The client retries 429 responses automatically (max_retries=2 by default) and exposes the latest rate-limit headers on client.rate_limit:
client.status()
print(client.rate_limit) # {'limit': 10, 'remaining': 9, 'reset': 1755590400}
Links
- API documentation
- Pricing — Free / $5 / $25 tiers
- League coverage
Development
pip install -e .
python -m unittest discover tests
License
Metadata
Release files for fivedollarfootball 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fivedollarfootball-0.1.5.tar.gz | 11.7 kB | Without provenance | Details for fivedollarfootball-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fivedollarfootball-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for fivedollarfootball-0.1.5-py3-none-any.whl |
Total release size: 21.7 kB
Release files / fivedollarfootball-0.1.5.tar.gz
| Download URL | fivedollarfootball-0.1.5.tar.gz |
|---|---|
| Size | 11.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1bff2d07554f390caaf88db38dc99c1b57a5476ec60e8ad1e3c3d5ac4ebf8682
|
|
BLAKE2b-256 checksum How to use checksums |
e0896b60919ef1c6c250248af84159566441ff67cbba926ff798552f121ce521
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / fivedollarfootball-0.1.5-py3-none-any.whl
| Download URL | fivedollarfootball-0.1.5-py3-none-any.whl |
|---|---|
| Size | 9.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ef2b03e8018d1011fe9a546e27c06b7190022e42e745436d1e9cb58b940e1acc
|
|
BLAKE2b-256 checksum How to use checksums |
9fc1ecffbe980800fce66f0f1f177ce0f92d8b46e8b84f701851491d265d5ace
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for fivedollarfootball 0.1.5
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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.