Metadata-Version: 2.4
Name: fivedollarfootball
Version: 0.1.1
Summary: Official Python client for the 5DollarFootballAPI — football fixtures, live scores, standings and odds history
Author: 5DollarFootballAPI
License: MIT
Project-URL: Homepage, https://5dollarfootballapi.com
Project-URL: Documentation, https://5dollarfootballapi.com/docs
Project-URL: Source, https://github.com/5dollarfootballapi/football-api-python-sdk
Keywords: football,soccer,api,odds,fixtures,live-scores,sports-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# 5DollarFootballAPI — Python client

Official Python client for the [5DollarFootballAPI](https://5dollarfootballapi.com): 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](https://5dollarfootballapi.com/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`)

Also available for Node.js: [`npm install fivedollarfootball`](https://github.com/5dollarfootballapi/football-api-js-sdk).

## Install

```bash
pip install fivedollarfootball
```

## Quickstart

Grab a free API key at [5dollarfootballapi.com](https://5dollarfootballapi.com) — the free tier covers the top-5 European leagues, no credit card required.

```python
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

```python
# 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

```python
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:

```python
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):

```python
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

```python
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`:

```python
client.status()
print(client.rate_limit)  # {'limit': 10, 'remaining': 9, 'reset': 1755590400}
```

## Links

- [API documentation](https://5dollarfootballapi.com/docs)
- [Pricing](https://5dollarfootballapi.com/pricing) — Free / $5 / $25 tiers
- [League coverage](https://5dollarfootballapi.com/coverage)

## Development

```bash
pip install -e .
python -m unittest discover tests
```

## License

[MIT](LICENSE)
