Quickstart

Make your first API call

Get up and running with Odds-API.io and fetch your first odds data.

Step 1: Get your API key

Visit odds-api.io and sign up for a free account.

Check your email

Your API key will be sent to the email address you provided during signup.

Copy your API key

Copy the API key from the email and keep it secure!

Never share your API key publicly or commit it to version control. Use environment variables to store it securely.

Step 2: Fetch available sports

Let’s start by fetching the list of available sports.

The /sports endpoint doesn’t require authentication - you can try it before getting your API key!

curl "https://api.odds-api.io/v3/sports"

const response = await fetch('https://api.odds-api.io/v3/sports');
const sports = await response.json();
console.log(sports);

import requests

response = requests.get('https://api.odds-api.io/v3/sports')
sports = response.json()
print(sports)

<?php
$response = file_get_contents('https://api.odds-api.io/v3/sports');
$sports = json_decode($response, true);
print_r($sports);

Example Response:

[
  {
    "name": "Football",
    "slug": "football"
  },
  {
    "name": "Basketball",
    "slug": "basketball"
  },
  {
    "name": "Tennis",
    "slug": "tennis"
  }
]

Step 3: Fetch events for a sport

Now let’s get upcoming football events:

curl "https://api.odds-api.io/v3/events?apiKey=YOUR_API_KEY&sport=football&limit=10"

const apiKey = process.env.ODDS_API_KEY;
const response = await fetch(
  `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&limit=10`
);
const events = await response.json();
console.log(events);

import requests
import os

api_key = os.environ['ODDS_API_KEY']
response = requests.get(
    'https://api.odds-api.io/v3/events',
    params={
        'apiKey': api_key,
        'sport': 'football',
        'limit': 10
    }
)
events = response.json()
print(events)

<?php
$apiKey = getenv('ODDS_API_KEY');
$url = 'https://api.odds-api.io/v3/events?' . http_build_query([
    'apiKey' => $apiKey,
    'sport' => 'football',
    'limit' => 10
]);
$response = file_get_contents($url);
$events = json_decode($response, true);
print_r($events);

Example Response:

[
  {
    "id": 123456,
    "sport": {
      "name": "Football",
      "slug": "football"
    },
    "league": {
      "name": "Premier League",
      "slug": "england-premier-league"
    },
    "home": "Manchester United",
    "away": "Liverpool",
    "date": "2025-10-15T15:00:00Z",
    "status": "settled",
    "scores": {
      "home": 2,
      "away": 1,
      "periods": {
        "p1": { "home": 1, "away": 0 },
        "ft": { "home": 2, "away": 1 }
      }
    }
  }
]

The scores object includes the final result (home/away, OT/penalty-inclusive) along with a periods map. Period keys: p1…pN (periods/sets/quarters), ft (full time), ot (overtime/extra time), ap (penalty shootout), currentgame (live tennis), map1…mapN (esports). The full-time key is ft (the legacy feed used fulltime).

Step 4: Get odds for an event

Finally, let’s fetch odds from multiple bookmakers for a specific event:

curl "https://api.odds-api.io/v3/odds?apiKey=YOUR_API_KEY&eventId=123456&bookmakers=Bet365,Unibet,SingBet"

const apiKey = process.env.ODDS_API_KEY;
const eventId = 123456;
const bookmakers = 'Bet365,Unibet,SingBet';

const response = await fetch(
  `https://api.odds-api.io/v3/odds?apiKey=${apiKey}&eventId=${eventId}&bookmakers=${bookmakers}`
);
const odds = await response.json();
console.log(odds);

import requests
import os

api_key = os.environ['ODDS_API_KEY']
event_id = 123456
bookmakers = 'Bet365,Unibet,SingBet'

response = requests.get(
    'https://api.odds-api.io/v3/odds',
    params={
        'apiKey': api_key,
        'eventId': event_id,
        'bookmakers': bookmakers
    }
)
odds = response.json()
print(odds)

<?php
$apiKey = getenv('ODDS_API_KEY');
$eventId = 123456;
$bookmakers = 'Bet365,Unibet,SingBet';

$url = 'https://api.odds-api.io/v3/odds?' . http_build_query([
    'apiKey' => $apiKey,
    'eventId' => $eventId,
    'bookmakers' => $bookmakers
]);
$response = file_get_contents($url);
$odds = json_decode($response, true);
print_r($odds);

Example Response:

{
  "id": 123456,
  "home": "Manchester United",
  "away": "Liverpool",
  "date": "2025-10-15T15:00:00Z",
  "status": "pending",
  "urls": {
    "Bet365": "https://www.bet365.com/...",
    "Unibet": "https://www.unibet.com/...",
    "SingBet": "https://www.unibet.com/..."
  },
  "bookmakers": {
    "Bet365": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.10",
            "draw": "3.40",
            "away": "3.20"
          }
        ],
        "updatedAt": "2025-10-04T10:30:00Z"
      }
    ],
    "Unibet": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.15",
            "draw": "3.35",
            "away": "3.15"
          }
        ],
        "updatedAt": "2025-10-04T10:29:45Z"
      }
    ],
    "SingBet": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.00",
            "draw": "3.25",
            "away": "3.25"
          }
        ],
        "updatedAt": "2025-10-04T10:29:42Z"
      }
    ]
  }
}

Common Use Cases

Here are quick snippets for common scenarios:

Find Best Odds for a Match

// Compare odds across bookmakers
const bestOdds = {};
Object.entries(odds.bookmakers).forEach(([bookmaker, markets]) => {
  const ml = markets.find(m => m.name === 'ML')?.odds[0];
  if (ml) {
    if (!bestOdds.home || parseFloat(ml.home) > parseFloat(bestOdds.home.odds)) {
      bestOdds.home = { bookmaker, odds: ml.home };
    }
  }
});

console.log(`Best home odds: ${bestOdds.home.odds} at ${bestOdds.home.bookmaker}`);

Filter Events by League

const apiKey = process.env.ODDS_API_KEY;

// Get Premier League matches only
const response = await fetch(
  `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&league=england-premier-league`
);

const matches = await response.json();
console.log(`Found ${matches.length} Premier League matches`);

Get Live Events

const apiKey = process.env.ODDS_API_KEY;

// Fetch events that are currently in play
const response = await fetch(
  `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&status=live`
);

const liveMatches = await response.json();
console.log(`${liveMatches.length} matches currently live`);

Keep Odds Live

Don’t poll /v3/odds on a timer. Open a WebSocket connection and let odds changes push to you as they happen:

const apiKey = process.env.ODDS_API_KEY;
const params = new URLSearchParams({ apiKey, markets: 'ML,Spread,Totals', sport: 'football' });

const ws = new WebSocket(`wss://api.odds-api.io/v3/ws?${params}`);
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'updated') {
    console.log(`${data.id} at ${data.bookie} changed`);
  }
};

Error Handling

Always handle errors gracefully in production:

async function fetchOdds(eventId) {
  const apiKey = process.env.ODDS_API_KEY;

  try {
    const response = await fetch(
      `https://api.odds-api.io/v3/odds?apiKey=${apiKey}&eventId=${eventId}&bookmakers=Bet365`
    );

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Invalid API key');
      }
      if (response.status === 429) {
        throw new Error('Rate limit exceeded - please wait before retrying');
      }
      if (response.status === 404) {
        throw new Error(`Event ${eventId} not found`);
      }
      throw new Error(`API error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to fetch odds:', error.message);
    throw error;
  }
}

Next steps

Now that you’ve made your first API calls, explore these guides:

WebSocket Feed

Real-time odds updates via WebSocket.

SDKs & Libraries

Official Python, Node.js, and MCP SDKs for faster integration.

Fetching Odds

Deep dive into fetching and comparing odds from multiple bookmakers.

Value Bets

Learn how prices above a fair-odds estimate are detected.

Need help? Contact us at hello@odds-api.io - we’re here to help!

Getting Started

Guides

Examples

Make your first API call

Step 1: Get your API key

Step 2: Fetch available sports

Step 3: Fetch events for a sport

Step 4: Get odds for an event

Common Use Cases

Find Best Odds for a Match

Filter Events by League

Get Live Events

Keep Odds Live

Error Handling

Next steps

WebSocket Feed

SDKs & Libraries

Fetching Odds

Value Bets

​Make your first API call

​Step 1: Get your API key

​Step 2: Fetch available sports

​Step 3: Fetch events for a sport

​Step 4: Get odds for an event

​Common Use Cases

​Find Best Odds for a Match

​Filter Events by League

​Get Live Events

​Keep Odds Live

​Error Handling

​Next steps

WebSocket Feed

SDKs & Libraries

Fetching Odds

Value Bets

Make your first API call

Step 1: Get your API key

Step 2: Fetch available sports

Step 3: Fetch events for a sport

Step 4: Get odds for an event

Common Use Cases

Find Best Odds for a Match

Filter Events by League

Get Live Events

Keep Odds Live

Error Handling

Next steps