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 and request_id
• Built-in pagination helper that walks has_more pages for you
• Python 3.8+, one dependency (requests)

Install

pip install fivedollarfootball

Until the package lands on PyPI you can install straight from GitHub:

pip install git+https://github.com/5dollarfootballapi/football-api-python-sdk.git

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

MIT