Odds-API.io Python SDK

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

Building with AI? See the AI and vibe coding guide. Prefer JavaScript? Check out the Node.js SDK.

🚀 Features

• ⚡ Fast & Reliable - Built on requests and aiohttp for both sync and async workflows
• 🏀 34 Sports - Basketball, football, tennis, baseball, and more
• 📊 365+ 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:

• 100 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:

• basic_usage.py - Getting started with the SDK
• async_example.py - Using the async client
• arbitrage_finder.py - Finding arbitrage opportunities
• value_bets.py - Identifying value bets
• settle_bets.py - Grading stored bets as won, lost or void
• odds_tracking.py - Tracking odds movements
• fair-odds-and-closing-lines.ipynb - Notebook: devigging, bookmaker margins, EV against a sharp line and closing line value (view on nbviewer)

🔧 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, markets)	Get recently updated odds. markets is required by the API from 15 October 2026	📖

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	📖

Settlement

Method	Description	Docs
get_settlements(event_ids)	Status, final score and final flag for up to 50 events	📖
grade_bets(selections)	Grade up to 50 bets as won, lost, void, half won or half lost	📖

⚠️ 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 - 365+ bookmakers across 34 sports and 12,000+ leagues
• ✅ 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
• 100 requests per hour
• 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

• Website: odds-api.io
• Documentation: docs.odds-api.io
• API Key: Get your API key
• GitHub: github.com/odds-api-io/odds-api-python
• Issues: Report a bug
• PyPI: pypi.org/project/odds-api-io

💬 Support

Need help? We're here for you:

• 📧 Email: hello@odds-api.io
• 📚 Documentation: docs.odds-api.io
• 🐛 Issues: GitHub Issues
• ⏱️ Response Time: Usually within 24 hours

⚡ Quick Links

• Get Started →
• View Documentation →
• See Examples →

---

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

Citation

If you use this package in research or a publication, please cite it. Citation metadata is in CITATION.cff (GitHub renders a "Cite this repository" button from it) and Zenodo metadata is in .zenodo.json.

Outlier AS. odds-api-io: Official Python SDK for Odds-API.io (version 1.0.2). https://github.com/odds-api-io/odds-api-python