A comprehensive Python library for The Odds API - Access sports betting odds from bookmakers around the world.
- Complete API Coverage: All endpoints including sports, odds, scores, events, historical data, and player props
- Type-Safe Models: Dataclass models for all API responses with proper type hints
- Convenient Constants: Pre-defined constants for sports, regions, markets, and odds formats
- Error Handling: Custom exceptions for different API error scenarios
- Usage Tracking: Built-in tracking of API request usage/quota
- Best Odds Finder: Utility method to find the best odds across bookmakers
- Context Manager Support: Use with
withstatement for automatic cleanup
pip install odds-api-clientOr install from source:
git clone https://github.com/your-username/odds-api-client.git
cd odds-api-client
pip install -e .from odds_api import OddsAPIClient, Sports, Regions, Markets
# Initialize the client
client = OddsAPIClient(api_key="your_api_key")
# Or use environment variable ODDS_API_KEY
# export ODDS_API_KEY="your_api_key"
# client = OddsAPIClient()
# Get available sports
sports = client.get_sports()
for sport in sports:
print(f"{sport.title} ({sport.key}) - Active: {sport.active}")
# Get NFL odds
odds = client.get_odds(
sport_key=Sports.NFL,
regions=[Regions.US],
markets=[Markets.HEAD_TO_HEAD, Markets.SPREADS, Markets.TOTALS]
)
for event in odds:
print(f"\n{event.home_team} vs {event.away_team}")
for bookmaker in event.bookmakers:
print(f" {bookmaker.title}:")
for market in bookmaker.markets:
print(f" {market.key}:")
for outcome in market.outcomes:
print(f" {outcome.name}: {outcome.price}")The main client class for interacting with The Odds API.
from odds_api import OddsAPIClient
client = OddsAPIClient(
api_key="your_api_key", # Required (or set ODDS_API_KEY env var)
base_url="https://api.the-odds-api.com/v4", # Optional
timeout=30 # Request timeout in seconds
)# Get all active (in-season) sports
sports = client.get_sports()
# Get all sports including out-of-season
all_sports = client.get_sports(all_sports=True)
# Get sports by group
basketball = client.get_sports_by_group("Basketball")from odds_api import Sports, Regions, Markets, OddsFormat
# Basic usage
odds = client.get_odds(
sport_key=Sports.NFL,
regions=Regions.US,
markets=Markets.HEAD_TO_HEAD
)
# Advanced usage with multiple regions and markets
odds = client.get_odds(
sport_key="basketball_nba",
regions=[Regions.US, Regions.UK, Regions.EU],
markets=[Markets.HEAD_TO_HEAD, Markets.SPREADS, Markets.TOTALS],
odds_format=OddsFormat.AMERICAN,
bookmakers=["fanduel", "draftkings", "betmgm"],
commence_time_from="2024-01-01T00:00:00Z",
commence_time_to="2024-01-31T23:59:59Z"
)
# Get response with usage info
response = client.get_odds_response(sport_key=Sports.NBA, regions="us")
print(f"Data: {len(response.data)} events")
print(f"Requests used: {response.usage.requests_used}")
print(f"Requests remaining: {response.usage.requests_remaining}")# Get upcoming events for a sport
events = client.get_events(sport_key=Sports.NBA)
for event in events:
print(f"{event.home_team} vs {event.away_team} at {event.commence_time}")# Get odds for a specific event
event_odds = client.get_event_odds(
sport_key=Sports.NBA,
event_id="abc123def456",
regions=Regions.US,
markets=[Markets.HEAD_TO_HEAD, Markets.SPREADS]
)# Get live and recent scores
scores = client.get_scores(
sport_key=Sports.NFL,
days_from=1 # Include completed games from past day
)
for score in scores:
if score.completed:
print(f"{score.home_team} vs {score.away_team} - FINAL")
for team_score in score.scores:
print(f" {team_score.name}: {team_score.score}")# Get player prop odds for a specific event
props = client.get_player_props(
sport_key=Sports.NBA,
event_id="abc123def456",
markets=[
Markets.PLAYER_POINTS,
Markets.PLAYER_REBOUNDS,
Markets.PLAYER_ASSISTS
]
)# Get historical odds snapshot (requires paid plan)
historical = client.get_historical_odds(
sport_key=Sports.NFL,
date="2023-10-15T12:00:00Z",
regions=Regions.US,
markets=Markets.HEAD_TO_HEAD
)# Find the best odds across all bookmakers
best_odds = client.get_best_odds(
sport_key=Sports.NFL,
regions=[Regions.US, Regions.UK],
market=Markets.HEAD_TO_HEAD
)
for event in best_odds:
print(f"\n{event['home_team']} vs {event['away_team']}")
for outcome, (price, bookmaker) in event['best_odds'].items():
print(f" {outcome}: {price} @ {bookmaker}")from odds_api import Sports
# American Football
Sports.NFL # "americanfootball_nfl"
Sports.NCAAF # "americanfootball_ncaaf"
# Basketball
Sports.NBA # "basketball_nba"
Sports.NCAAB # "basketball_ncaab"
Sports.WNBA # "basketball_wnba"
# Baseball
Sports.MLB # "baseball_mlb"
# Hockey
Sports.NHL # "icehockey_nhl"
# Soccer
Sports.EPL # "soccer_epl"
Sports.LA_LIGA # "soccer_spain_la_liga"
Sports.BUNDESLIGA # "soccer_germany_bundesliga"
Sports.SERIE_A # "soccer_italy_serie_a"
Sports.MLS # "soccer_usa_mls"
# And many more...from odds_api import Regions
Regions.US # US bookmakers (FanDuel, DraftKings, etc.)
Regions.US2 # Additional US bookmakers
Regions.UK # UK bookmakers (William Hill, Ladbrokes, etc.)
Regions.EU # European bookmakers (Pinnacle, 1xBet, etc.)
Regions.AU # Australian bookmakers (Sportsbet, TAB, etc.)from odds_api import Markets
# Standard markets
Markets.HEAD_TO_HEAD # Moneyline
Markets.SPREADS # Point spreads
Markets.TOTALS # Over/Under
Markets.OUTRIGHTS # Futures
# Player props (NBA)
Markets.PLAYER_POINTS
Markets.PLAYER_REBOUNDS
Markets.PLAYER_ASSISTS
Markets.PLAYER_THREES
# Player props (NFL)
Markets.PLAYER_PASS_TDS
Markets.PLAYER_PASS_YDS
Markets.PLAYER_RUSH_YDS
Markets.PLAYER_RECEPTIONS
# And many more...from odds_api import (
OddsAPIClient,
OddsAPIError,
AuthenticationError,
RateLimitError,
QuotaExceededError,
NotFoundError,
InvalidParameterError
)
try:
client = OddsAPIClient(api_key="your_api_key")
odds = client.get_odds(sport_key="invalid_sport")
except AuthenticationError as e:
print(f"Invalid API key: {e}")
except RateLimitError as e:
print(f"Rate limit exceeded: {e}")
except QuotaExceededError as e:
print(f"Monthly quota exceeded: {e}")
except NotFoundError as e:
print(f"Sport not found: {e}")
except InvalidParameterError as e:
print(f"Invalid parameters: {e}")
except OddsAPIError as e:
print(f"API error: {e}")from odds_api import OddsAPIClient
with OddsAPIClient(api_key="your_api_key") as client:
sports = client.get_sports()
odds = client.get_odds("basketball_nba")
# Session is automatically closedclient = OddsAPIClient(api_key="your_api_key")
# Make some requests
sports = client.get_sports()
odds = client.get_odds("basketball_nba")
# Check usage after requests
if client.usage:
print(f"Requests used: {client.usage.requests_used}")
print(f"Requests remaining: {client.usage.requests_remaining}")All API responses are parsed into dataclass models:
Sport- Sport informationEvent- Event/game informationScore/TeamScore- Score informationEventOdds- Event with odds from bookmakersBookmaker- Bookmaker with their marketsMarket- Betting market (h2h, spreads, etc.)Outcome- Individual betting outcomePlayerProp/PlayerPropMarket/PlayerPropOutcome- Player prop modelsUsageInfo- API usage trackingAPIResponse- Response wrapper with usage info
- Python 3.8+
- requests >= 2.28.0
MIT License - see LICENSE file for details.