Skip to content

README.md

Latest commit

 

History

History
277 lines (202 loc) · 9.88 KB

README.md

File metadata and controls

277 lines (202 loc) · 9.88 KB

Odds-API.io Python SDK

PyPI version Python versions License: MIT Documentation

Official Python SDK for Odds-API.io - Real-time sports betting odds from 250+ bookmakers.

🚀 Features

  • ⚡ Fast & Reliable - Built on requests and aiohttp for both sync and async workflows
  • 🏀 20+ Sports - Basketball, football, tennis, baseball, and more
  • 📊 250+ Bookmakers - Comprehensive odds coverage from major sportsbooks worldwide
  • 💰 Arbitrage Detection - Find risk-free betting opportunities across bookmakers
  • 📈 Value Bets - Identify positive expected value betting opportunities
  • 🔴 Live Events - Real-time in-play event tracking and odds
  • 🔍 Advanced Search - Search events, participants, and leagues
  • ✨ Type Hints - Full type annotations for better IDE support
  • 🐍 Modern Python - Supports Python 3.8+

📦 Installation

pip install odds-api-io

🔑 Get Your API Key

Get your free API key here →

Sign up at odds-api.io to get started. Free tier includes:

  • 5,000 requests/hour
  • Access to all endpoints
  • No credit card required

📚 Documentation

Full API documentation is available at docs.odds-api.io

🏃 Quick Start

Synchronous Client

from odds_api import OddsAPIClient

# Initialize the client
client = OddsAPIClient(api_key="your_api_key_here")

# Get available sports
sports = client.get_sports()
print(f"Found {len(sports)} sports")

# Get upcoming NBA events
events = client.get_events(sport="basketball", league="usa-nba")

# Search for specific games
lakers_games = client.search_events(query="Lakers")

# Get live basketball events
live = client.get_live_events(sport="basketball")

# Find arbitrage opportunities
arb_bets = client.get_arbitrage_bets(
    bookmakers="singbet,bet365",
    limit=10,
    include_event_details=True
)

# Close the client when done
client.close()

Asynchronous Client

import asyncio
from odds_api import AsyncOddsAPIClient

async def main():
    # Use async context manager
    async with AsyncOddsAPIClient(api_key="your_api_key_here") as client:
        # Get sports
        sports = await client.get_sports()
        
        # Get upcoming events
        events = await client.get_events(sport="basketball", league="usa-nba")
        
        # Find value bets
        value_bets = await client.get_value_bets(
            bookmaker="singbet",
            include_event_details=True
        )
        
        print(f"Found {len(value_bets)} value betting opportunities")

# Run async code
asyncio.run(main())

Context Manager (Recommended)

# Sync
with OddsAPIClient(api_key="your_api_key") as client:
    sports = client.get_sports()

# Async
async with AsyncOddsAPIClient(api_key="your_api_key") as client:
    sports = await client.get_sports()

📖 Examples

Check out the examples/ directory for more detailed examples:

🔧 API Reference

Sports & Leagues

Method Description Docs
get_sports() Get all available sports 📖
get_leagues(sport) Get leagues for a sport 📖

Events

Method Description Docs
get_events(sport, **filters) Get events with filters 📖
get_event_by_id(event_id) Get specific event details 📖
get_live_events(sport) Get currently live events 📖
search_events(query) Search events by keyword 📖

Odds

Method Description Docs
get_event_odds(event_id, bookmakers) Get odds for an event 📖
get_odds_movement(event_id, bookmaker, market) Track odds changes 📖
get_odds_for_multiple_events(event_ids, bookmakers) Get odds for multiple events 📖
get_updated_odds_since_timestamp(since, bookmaker, sport) Get recently updated odds 📖

Participants

Method Description Docs
get_participants(sport, search=None) Get teams/players 📖
get_participant_by_id(participant_id) Get participant by ID 📖

Bookmakers

Method Description Docs
get_bookmakers() Get all available bookmakers 📖
get_selected_bookmakers() Get your selected bookmakers 📖
select_bookmakers(bookmakers) Select bookmakers 📖
clear_selected_bookmakers() Clear selection 📖

Betting Analysis

Method Description Docs
get_arbitrage_bets(bookmakers, **options) Find arbitrage opportunities 📖
get_value_bets(bookmaker, **options) Find value bets 📖

⚠️ Error Handling

The SDK provides custom exceptions for different error scenarios:

from odds_api import (
    OddsAPIClient,
    OddsAPIError,
    InvalidAPIKeyError,
    RateLimitExceededError,
    NotFoundError,
    ValidationError
)

client = OddsAPIClient(api_key="your_api_key")

try:
    events = client.get_events(sport="basketball")
except InvalidAPIKeyError:
    print("Your API key is invalid")
except RateLimitExceededError:
    print("Rate limit exceeded - wait before retrying")
except NotFoundError:
    print("Resource not found")
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except OddsAPIError as e:
    print(f"API error: {e}")

🌟 Why Odds-API.io?

  • ✅ Most Comprehensive Coverage - 250+ bookmakers across 20+ sports
  • ✅ Near-Zero Latency - Real-time odds updates with minimal delay
  • ✅ Direct Bet Links - Deep links directly to bookmaker bet slips
  • ✅ Value Bet Detection - Automatically calculated expected value
  • ✅ Historical Data - Access to past odds and results
  • ✅ Developer Friendly - Clean API design with excellent documentation

💡 Use Cases

Build powerful betting tools and analytics:

  • 🎯 Arbitrage betting platforms
  • 📊 Odds comparison sites
  • 📈 Value betting calculators
  • 🤖 Automated betting systems
  • 📉 Sports analytics dashboards
  • 🔔 Odds movement alerts

🆓 Free Tier Limitations

  • Limited to 2 bookmakers selected at once
  • 5,000 requests per hour (shared across all plans)
  • No WebSocket access on free tier

Upgrade for more features →

📋 Requirements

  • Python 3.8 or higher
  • requests library (for sync client)
  • aiohttp library (for async client)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

💬 Support

Need help? We're here for you:

⚡ Quick Links

Built with ❤️ by the Odds-API.io team