Odds API Documentation
# 🎲 Odds API Documentation
## Table of Contents
- [Introduction](#introduction)
- [API Overview](#api-overview)
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [Request & Response Formats](#request--response-formats)
- [Pagination](#pagination)
- [Rate Limiting](#rate-limiting)
- [Error Handling](#error-handling)
- [Webhooks](#webhooks)
- [SDK Integration](#sdk-integration)
- [Examples](#examples)
- [FAQ](#faq)
## Introduction
Welcome to the Odds API – a robust, high-performance system designed to deliver real-time sports betting odds and statistics. This API provides developers with seamless access to comprehensive odds data across multiple sports, bookmakers, and markets.
### Key Features
- **Real-time data**: Access odds with millisecond latency
- **Global coverage**: Data from 200+ bookmakers across 40+ sports
- **Historical archive**: Odds history dating back 5+ years
- **Flexible formatting**: JSON, XML, and CSV response options
- **Webhooks**: Real-time notifications for odds changes
- **Comprehensive statistics**: Pre-game and in-play metrics
## API Overview
The Odds API follows REST architecture principles and uses standard HTTP methods. Here's a high-level architectural overview:
```mermaid
flowchart TB
Client[Client Application] <--> API[Odds API Gateway]
API <--> Auth[Authentication Service]
API <--> Rate[Rate Limiting Service]
API <--> Cache[Cache Layer]
Cache <--> Data[Data Processing Engine]
Data <--> Store[(Data Store)]
Data <--> Feed[Live Data Feeds]
API <--> Webhook[Webhook Service]
```
## Authentication
The API uses OAuth 2.0 for secure authentication. All requests must include a valid access token.
### Obtaining API Keys
1. Register at our [Developer Portal](https://api.odds.example/register)
2. Create a new application to receive your `client_id` and `client_secret`
3. Use these credentials to request an access token
### Access Token Request
```bash
curl -X POST https://api.odds.example/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
```
### Authentication Flow
```mermaid
sequenceDiagram
Client->>Auth Service: POST /oauth/token
Note right of Client: client_id & client_secret
Auth Service->>Auth Service: Validate credentials
Auth Service->>Client: Return access_token
Client->>API Gateway: API request with access_token
API Gateway->>Auth Service: Validate token
Auth Service->>API Gateway: Token validation result
API Gateway->>Client: API response
```
## Endpoints
### Base URL
```
https://api.odds.example/v2
```
### Available Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sports` | GET | List all available sports |
| `/sports/{sport_key}/odds` | GET | Get latest odds for a sport |
| `/sports/{sport_key}/events` | GET | List upcoming events |
| `/sports/{sport_key}/events/{event_id}` | GET | Get detailed event information |
| `/sports/{sport_key}/events/{event_id}/odds` | GET | Get odds for a specific event |
| `/bookmakers` | GET | List all bookmakers |
| `/markets` | GET | List all bet markets |
## Request & Response Formats
### Request Format
API requests should include:
- **Authorization header** with your access token
- **Content-Type header** specifying accepted response format
- **Query parameters** for filtering, sorting, and pagination
Example request:
```bash
curl -X GET "https://api.odds.example/v2/sports/soccer_epl/odds?markets=h2h,spreads&bookmakers=pinnacle,betmgm" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/json"
```
### Response Format
Responses are available in JSON (default), XML, or CSV formats. Specify your preference using the `Accept` header.
Sample JSON response:
```json
{
"success": true,
"data": {
"sport_key": "soccer_epl",
"sport_title": "English Premier League",
"events": [
{
"id": "evt_123456",
"commence_time": "2023-10-15T15:00:00Z",
"home_team": "Arsenal",
"away_team": "Chelsea",
"bookmakers": [
{
"key": "pinnacle",
"title": "Pinnacle",
"last_update": "2023-10-15T12:30:45Z",
"markets": [
{
"key": "h2h",
"outcomes": [
{
"name": "Arsenal",
"price": 2.05
},
{
"name": "Chelsea",
"price": 3.75
},
{
"name": "Draw",
"price": 3.20
}
]
}
]
}
]
}
]
},
"meta": {
"timestamp": "2023-10-15T12:45:32Z",
"count": 1,
"delta_last_update": 125
}
}
```
## Pagination
For endpoints returning large datasets, pagination is supported using the following parameters:
- `page`: Page number (starting from 1)
- `per_page`: Number of items per page (default 20, max 100)
Response includes pagination metadata:
```json
{
"pagination": {
"current_page": 1,
"per_page": 20,
"total_pages": 5,
"total_count": 97
}
}
```
## Rate Limiting
To ensure fair usage, the API implements rate limiting based on your subscription tier:
| Plan | Rate Limit | Burst Capacity |
|------|------------|----------------|
| Basic | 10 req/sec | 20 requests |
| Pro | 50 req/sec | 100 requests |
| Enterprise | 200 req/sec | 400 requests |
Rate limit information is included in response headers:
```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1665842400
```
## Error Handling
The API uses standard HTTP status codes and returns detailed error information:
```json
{
"success": false,
"error": {
"code": "invalid_parameter",
"message": "The sport_key parameter contains an invalid value",
"details": {
"parameter": "sport_key",
"provided": "soccer_xyz",
"valid_values": [
"soccer_epl",
"soccer_la_liga",
"soccer_bundesliga"
]
}
}
}
```
### Common Error Codes
| HTTP Status | Error Code | Description |
|-------------|------------|-------------|
| 400 | `invalid_parameter` | One or more parameters are invalid |
| 401 | `unauthorized` | Authentication required or failed |
| 403 | `forbidden` | Valid authentication but insufficient permissions |
| 404 | `not_found` | Resource not found |
| 429 | `rate_limit_exceeded` | Request rate limit exceeded |
| 500 | `server_error` | Unexpected server error |
## Webhooks
Receive real-time notifications when odds change by subscribing to webhooks.
### Setting up a Webhook
```bash
curl -X POST "https://api.odds.example/v2/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.example/webhook",
"events": ["odds.update", "game.start", "game.end"],
"sports": ["soccer_epl", "basketball_nba"],
"secret": "your_webhook_secret"
}'
```
### Webhook Flow
```mermaid
sequenceDiagram
participant Feed as Data Feed
participant API as Odds API
participant Sub as Webhook Subscriber
Feed->>API: New odds data
API->>API: Process and detect changes
API->>Sub: POST webhook event
Sub->>Sub: Verify signature
Sub->>API: 200 OK
Note over API,Sub: If delivery fails, API retries with exponential backoff
```
### Webhook Payload Example
```json
{
"event_type": "odds.update",
"timestamp": "2023-10-15T14:22:33Z",
"sport_key": "soccer_epl",
"event_id": "evt_123456",
"bookmaker": "pinnacle",
"market": "h2h",
"previous": [
{
"name": "Arsenal",
"price": 2.10
},
{
"name": "Chelsea",
"price": 3.65
},
{
"name": "Draw",
"price": 3.25
}
],
"current": [
{
"name": "Arsenal",
"price": 2.05
},
{
"name": "Chelsea",
"price": 3.75
},
{
"name": "Draw",
"price": 3.20
}
],
"signature": "sha256=..."
}
```
## SDK Integration
We provide official SDKs for popular programming languages:
| Language | Installation | GitHub |
|----------|-------------|--------|
| Python | `pip install odds-api-client` | [GitHub](https://github.com/odds-api/python-client) |
| JavaScript | `npm install odds-api-client` | [GitHub](https://github.com/odds-api/js-client) |
| PHP | `composer require odds-api/client` | [GitHub](https://github.com/odds-api/php-client) |
| Ruby | `gem install odds_api_client` | [GitHub](https://github.com/odds-api/ruby-client) |
| Go | `go get github.com/odds-api/go-client` | [GitHub](https://github.com/odds-api/go-client) |
### SDK Usage Example (Python)
```python
from odds_api_client import OddsAPIClient
# Initialize client
client = OddsAPIClient(api_key="YOUR_API_KEY")
# Get odds for NFL
odds = client.get_odds(
sport="americanfootball_nfl",
markets=["h2h", "spreads"],
bookmakers=["fanduel", "draftkings"]
)
# Process the data
for event in odds["events"]:
print(f"{event['home_team']} vs {event['away_team']}")
for bookmaker in event["bookmakers"]:
print(f" {bookmaker['title']} odds:")
for market in bookmaker["markets"]:
print(f" {market['key']}:")
for outcome in market["outcomes"]:
print(f" {outcome['name']}: {outcome['price']}")
```
## Examples
### Fetch Upcoming Games
```bash
curl -X GET "https://api.odds.example/v2/sports/basketball_nba/events?timeframe=upcoming&limit=5" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Compare Odds Across Bookmakers
```bash
curl -X GET "https://api.odds.example/v2/sports/tennis_atp_aus_open/events/evt_789012/odds?markets=h2h&bookmakers=pinnacle,bet365,draftkings" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Historical Odds Query
```bash
curl -X GET "https://api.odds.example/v2/sports/soccer_fifa_world_cup/events/evt_456789/odds/history?market=h2h&bookmaker=betmgm&from=2022-11-20T00:00:00Z&to=2022-11-21T00:00:00Z" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Data Flow Architecture
The following diagram illustrates how data flows through the Odds API system:
```mermaid
graph TD
A[Bookmaker Data Sources] --> B{Data Collection Service}
B --> C[(Raw Data Store)]
C --> D{Data Processing Engine}
D --> E[(Processed Data Store)]
D --> F[Anomaly Detection]
F -- Anomalies --> G[Human Review]
G --> D
E --> H{API Gateway}
H --> I[Caching Layer]
I --> J[Client Applications]
K[Real-time Feed Service] --> L{Feed Processing}
L --> M[Event Queue]
M --> N{Webhook Service}
N --> O[Client Webhooks]
M --> P{Real-time API}
P --> Q[WebSocket Clients]
```
## FAQ
### How fresh is your odds data?
Our odds data is updated in real-time with typical latency under 500ms from bookmaker updates.
### Do you support in-play odds?
Yes, we provide both pre-game and in-play odds across supported sports and bookmakers.
### How do I report API issues?
Please contact our support team at [email protected] or open an issue on our [GitHub repository](https://github.com/odds-api/issues).
### What is the uptime guarantee?
Our Enterprise tier includes a 99.99% uptime SLA. All tiers benefit from our highly available infrastructure spread across multiple regions.
### How do I convert decimal odds to other formats?
Use our conversion endpoints or formula:
- American: `(decimal - 1) * 100` for decimal > 2, `-100 / (decimal - 1)` for decimal < 2
- Fractional: Decimal odds - 1, expressed as a fraction
---
## Getting Started
1. [Register](https://api.odds.example/register) for an API key
2. Explore our [interactive documentation](https://api.odds.example/docs)
3. Test requests in our [API playground](https://api.odds.example/playground)
4. Join our [developer community](https://community.odds.example)
For technical support, contact us at [[email protected]](mailto:[email protected]) or join our [Slack channel](https://slack.odds.example).
---
© 2023 Odds API Inc. All rights reserved.