Test
# Odds API Documentation
## Overview
Welcome to the Odds API documentation. This API provides comprehensive sports betting odds data, including pre-game and live odds, line movements, and historical data across multiple sports and bookmakers.
## Authentication
All API requests require an API key for authentication.
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: Request with API key
alt Valid API key
API->>Client: Return requested data
else Invalid API key
API->>Client: Return 401 Unauthorized
end
```
### Obtaining an API Key
1. Register at [our developer portal](https://example.com/register)
2. Navigate to the API Keys section
3. Generate a new API key
4. Include this key in all API requests
### Authentication Example
```bash
curl -X GET "https://api.odds.com/v1/sports" \
-H "x-api-key: your_api_key_here"
```
## Base URL
All API requests should be made to:
```
https://api.odds.com/v1/
```
## Rate Limiting
The API implements rate limiting to ensure fair usage.
| Plan | Requests per minute | Daily limit |
|------|---------------------|-------------|
| Free | 10 | 1,000 |
| Pro | 60 | 10,000 |
| Enterprise | 300 | Unlimited |
```mermaid
graph TD
A[API Request] --> B{Check Rate Limit}
B -->|Within limit| C[Process Request]
B -->|Exceeded| D[Return 429 Too Many Requests]
C --> E[Return Data]
```
## Error Handling
The API uses standard HTTP response codes to indicate success or failure.
| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong on our end |
## Endpoints
### List Sports
Returns a list of available sports.
**Endpoint:** `GET /sports`
**Query Parameters:** None
**Response:**
```json
{
"sports": [
{
"id": "soccer",
"name": "Soccer",
"active": true
},
{
"id": "basketball",
"name": "Basketball",
"active": true
}
]
}
```
### List Leagues
Returns available leagues for a specific sport.
**Endpoint:** `GET /sports/{sport_id}/leagues`
**Query Parameters:** None
**Response:**
```json
{
"leagues": [
{
"id": "epl",
"name": "English Premier League",
"country": "England"
},
{
"id": "laliga",
"name": "La Liga",
"country": "Spain"
}
]
}
```
### Get Odds
Retrieves current odds for matches in a specific sport and league.
**Endpoint:** `GET /odds/{sport_id}`
**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| league_id | string | No | Filter by league |
| bookmakers | string | No | Comma-separated list of bookmaker IDs |
| markets | string | No | Comma-separated list of market types (e.g., h2h, spreads, totals) |
| date_format | string | No | Format for dates (iso, unix) |
**Response:**
```json
{
"sport_id": "soccer",
"league_id": "epl",
"odds": [
{
"id": "match_123",
"home_team": "Manchester United",
"away_team": "Liverpool",
"start_time": "2023-10-21T15:00:00Z",
"bookmakers": [
{
"id": "betfair",
"name": "Betfair",
"markets": [
{
"key": "h2h",
"last_update": "2023-10-20T08:15:00Z",
"outcomes": [
{
"name": "Manchester United",
"price": 2.5
},
{
"name": "Liverpool",
"price": 2.7
},
{
"name": "Draw",
"price": 3.4
}
]
}
]
}
]
}
]
}
```
### Get Line History
Retrieves historical line movements for a specific match.
**Endpoint:** `GET /odds/{sport_id}/{match_id}/history`
**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| bookmakers | string | No | Comma-separated list of bookmaker IDs |
| markets | string | No | Comma-separated list of market types |
| from_date | string | No | Start date (ISO format) |
| to_date | string | No | End date (ISO format) |
**Response:**
```json
{
"match_id": "match_123",
"home_team": "Manchester United",
"away_team": "Liverpool",
"history": [
{
"timestamp": "2023-10-15T12:00:00Z",
"bookmaker": "betfair",
"market": "h2h",
"outcomes": [
{
"name": "Manchester United",
"price": 2.6
},
{
"name": "Liverpool",
"price": 2.5
},
{
"name": "Draw",
"price": 3.5
}
]
},
{
"timestamp": "2023-10-18T14:30:00Z",
"bookmaker": "betfair",
"market": "h2h",
"outcomes": [
{
"name": "Manchester United",
"price": 2.5
},
{
"name": "Liverpool",
"price": 2.7
},
{
"name": "Draw",
"price": 3.4
}
]
}
]
}
```
## Data Models
### Odds Flow Diagram
```mermaid
flowchart LR
A[Sports] --> B[Leagues]
B --> C[Matches]
C --> D[Bookmakers]
D --> E[Markets]
E --> F[Outcomes/Odds]
```
### Market Types
```mermaid
classDiagram
class Market {
+String key
+DateTime last_update
+List~Outcome~ outcomes
}
class Outcome {
+String name
+float price
+float point
}
Market "1" -- "many" Outcome
```
The API supports the following market types:
| Key | Description |
|-----|-------------|
| h2h | Head to head (moneyline) |
| spreads | Point spreads (handicaps) |
| totals | Over/under totals |
| outrights | Outright winners (futures) |
| props | Proposition bets |
## Webhooks
The API supports webhooks for real-time odds updates.
```mermaid
sequenceDiagram
participant API
participant Your Server
API->>Your Server: POST odds update to your webhook URL
Your Server->>API: Return 200 OK
Note over API,Your Server: If your server doesn't respond with 200 OK,<br>we'll retry the webhook 3 times
```
### Setting Up Webhooks
1. Register a webhook URL in the developer portal
2. Choose the events you want to subscribe to
3. We'll send POST requests to your URL when those events occur
### Webhook Payload Example
```json
{
"event_type": "odds_change",
"sport_id": "soccer",
"match_id": "match_123",
"bookmaker_id": "betfair",
"market_key": "h2h",
"timestamp": "2023-10-20T14:25:33Z",
"previous_odds": [
{
"name": "Manchester United",
"price": 2.6
},
{
"name": "Liverpool",
"price": 2.6
},
{
"name": "Draw",
"price": 3.3
}
],
"current_odds": [
{
"name": "Manchester United",
"price": 2.5
},
{
"name": "Liverpool",
"price": 2.7
},
{
"name": "Draw",
"price": 3.4
}
]
}
```
## API Usage Examples
### Fetching Soccer Odds for the Premier League
```javascript
// Example using JavaScript fetch
const fetchPremierLeagueOdds = async () => {
const response = await fetch(
'https://api.odds.com/v1/odds/soccer?league_id=epl&markets=h2h,spreads',
{
headers: {
'x-api-key': 'your_api_key_here'
}
}
);
const data = await response.json();
return data;
};
```
### Tracking Line Movement
```python
# Example using Python requests
import requests
def track_line_movement(match_id, days=7):
url = f"https://api.odds.com/v1/odds/soccer/{match_id}/history"
headers = {
"x-api-key": "your_api_key_here"
}
params = {
"markets": "h2h",
"bookmakers": "betfair,pinnacle",
"from_date": "2023-10-14T00:00:00Z"
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
else:
return {"error": response.status_code, "message": response.text}
```
## Integration Architecture
```mermaid
graph TD
A[Your Application] -->|API Requests| B[Odds API]
B -->|Response Data| A
B -->|Webhook Updates| A
C[Sports Data Sources] -->|Data Collection| B
D[Bookmakers] -->|Odds Collection| B
subgraph "Odds API Infrastructure"
B
E[Authentication Service]
F[Data Processing]
G[Database]
H[Webhook Service]
end
B -->|Validate| E
B -->|Process| F
F -->|Store/Retrieve| G
B -->|Trigger| H
```
## Best Practices
1. **Cache data** when appropriate to reduce API calls
2. **Implement retry logic** with exponential backoff for failed requests
3. **Monitor rate limits** to avoid service disruption
4. **Set up webhooks** for real-time updates instead of frequent polling
5. **Handle timezone differences** correctly when working with match start times
## SDK Libraries
We provide official SDK libraries for popular programming languages:
- [JavaScript/Node.js](https://github.com/odds-api/odds-api-js)
- [Python](https://github.com/odds-api/odds-api-python)
- [PHP](https://github.com/odds-api/odds-api-php)
- [Ruby](https://github.com/odds-api/odds-api-ruby)
- [Java](https://github.com/odds-api/odds-api-java)
## Support
If you encounter any issues or have questions about the API:
1. Check the [FAQ section](https://example.com/faq)
2. Browse our [community forum](https://example.com/forum)
3. Contact support at [email protected]
## Changelog
```mermaid
timeline
title API Version History
section v1.0
Released: 2023-01-15
Initial API release
section v1.1
Released: 2023-03-20
Added historical odds
Improved error handling
section v1.2
Released: 2023-06-10
Added webhooks
Extended market coverage
section v1.3
Released: 2023-09-05
Added live odds
Improved rate limits
```
### Detailed Changelog
#### v1.3 (Current)
- Added live betting odds
- Increased rate limits for all subscription tiers
- Added support for esports
- Performance improvements
#### v1.2
- Introduced webhooks for real-time updates
- Added prop bets and more specialized markets
- Extended coverage to more regional leagues
- Added SDK libraries for major programming languages
#### v1.1
- Added historical odds endpoint
- Improved error messages and documentation
- Fixed timezone inconsistencies
- Added more filtering options
#### v1.0
- Initial API release
- Support for major sports and bookmakers
- Basic odds retrieval functionality