How Soccer Odds APIs Work (With Real Examples)

Match
  └── Bookmaker
      └── Market
          └── Selection
              ├── Price
              ├── Odds format
              ├── Status
              ├── Live or pre-match
              └── Updated timestamp

GET /v1/soccer/matches/match_74021/odds

Authorization: Bearer YOUR_API_KEY
Accept: application/json

{
  "data": {
    "match_id": "match_74021",
    "status": "scheduled",
    "starts_at": "2026-08-06T18:00:00Z",
    "bookmakers": [
      {
        "bookmaker_id": "bookmaker_12",
        "name": "Example Sportsbook",
        "markets": [
          {
            "market_id": "market_match_winner",
            "name": "Match Winner",
            "status": "open",
            "is_live": false,
            "outcomes": [
              {
                "selection_id": "home",
                "name": "North City",
                "price": 1.84,
                "price_format": "decimal"
              },
              {
                "selection_id": "draw",
                "name": "Draw",
                "price": 3.45,
                "price_format": "decimal"
              },
              {
                "selection_id": "away",
                "name": "United Athletic",
                "price": 4.20,
                "price_format": "decimal"
              }
            ]
          }
        ]
      }
    ],
    "updated_at": "2026-08-06T10:30:18Z"
  }
}

{
  "data": {
    "match_id": "match_74021",
    "match_status": "live",
    "minute": 67,
    "score": {
      "home": 2,
      "away": 1
    },
    "bookmakers": [
      {
        "bookmaker_id": "bookmaker_12",
        "markets": [
          {
            "market_id": "market_match_winner",
            "status": "open",
            "is_live": true,
            "outcomes": [
              {
                "selection_id": "home",
                "price": 1.36
              },
              {
                "selection_id": "draw",
                "price": 4.80
              },
              {
                "selection_id": "away",
                "price": 10.50
              }
            ]
          }
        ]
      }
    ],
    "updated_at": "2026-08-06T19:24:12Z"
  }
}

{
  "market_id": "market_match_winner",
  "status": "suspended",
  "is_live": true,
  "suspended_at": "2026-08-06T19:24:05Z",
  "reason": "important_match_event"
}

Decimal odds: 2.50
Stake: 10

Total return:
10 × 2.50 = 25

Profit:
25 - 10 = 15

Fractional odds: 3/2
Stake: 10

Profit:
10 × 3 / 2 = 15

Total return:
15 + 10 = 25

Positive odds: +150
Stake: 100
Profit: 150

Negative odds: -200
Stake required to win 100: 200

fractional value = decimal odds - 1

Example:
2.50 - 1 = 1.50
1.50 = 3/2

If decimal odds are 2.00 or greater:

American = (decimal - 1) × 100

If decimal odds are below 2.00:

American = -100 / (decimal - 1)

function decimalToAmerican(decimalOdds) {
  if (!Number.isFinite(decimalOdds) || decimalOdds <= 1) {
    throw new Error('Decimal odds must be greater than 1.');
  }

  if (decimalOdds >= 2) {
    return Math.round((decimalOdds - 1) * 100);
  }

  return Math.round(-100 / (decimalOdds - 1));
}

Implied probability = 1 / decimal odds

Example:
1 / 2.50 = 0.40

Implied probability:
40%

Home: 2.00
Draw: 3.50
Away: 4.00

Home:
1 / 2.00 = 50.00%

Draw:
1 / 3.50 = 28.57%

Away:
1 / 4.00 = 25.00%

Total:
103.57%

Do not compare:

"Match Result"
"1X2"
"Full Time Result"

using text labels alone.

Instead compare:

market_id = "market_match_winner"

function normaliseOutcome({
  match,
  bookmaker,
  market,
  outcome,
  updatedAt
}) {
  return {
    matchId: match.id,
    bookmakerId: bookmaker.id,
    marketId: market.id,
    selectionId: outcome.id,
    line: outcome.line ?? null,
    price: Number(outcome.price),
    format: outcome.format ?? 'decimal',
    status: market.status,
    isLive: Boolean(market.is_live),
    updatedAt
  };
}

{
  "match_id": "match_74021",
  "bookmaker_id": "bookmaker_12",
  "market_id": "market_match_winner",
  "selection_id": "home",
  "price": 1.84,
  "price_format": "decimal",
  "is_live": false,
  "market_status": "open",
  "captured_at": "2026-08-06T10:30:18Z"
}

const matchId = 'match_74021';

const response = await fetch(
  `/api/soccer/matches/${encodeURIComponent(matchId)}/odds`
);

if (!response.ok) {
  throw new Error(`Odds request failed: ${response.status}`);
}

const payload = await response.json();

for (const bookmaker of payload.data.bookmakers) {
  for (const market of bookmaker.markets) {
    if (market.status !== 'open') {
      continue;
    }

    console.log(bookmaker.name, market.name, market.outcomes);
  }
}

import requests

match_id = "match_74021"

response = requests.get(
    (
        "https://api.example.com/v1/soccer/"
        f"matches/{match_id}/odds"
    ),
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
    timeout=15,
)

response.raise_for_status()
odds = response.json()

<?php

$matchId = 'match_74021';

$url = sprintf(
    'https://api.example.com/v1/soccer/matches/%s/odds',
    rawurlencode($matchId)
);

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 15,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        'Soccer odds API returned HTTP ' . $status
    );
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

let liveOddsTimer;

function startLiveOddsPolling(matchId) {
  stopLiveOddsPolling();

  liveOddsTimer = setInterval(async () => {
    try {
      await loadLiveOdds(matchId);
    } catch (error) {
      console.error(error);
    }
  }, 15000);
}

function stopLiveOddsPolling() {
  if (liveOddsTimer) {
    clearInterval(liveOddsTimer);
    liveOddsTimer = undefined;
  }
}

const socket = new WebSocket(
  'wss://stream.example.com/v1/soccer'
);

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    action: 'authenticate',
    token: 'SHORT_LIVED_ACCESS_TOKEN'
  }));

  socket.send(JSON.stringify({
    action: 'subscribe',
    channel: 'soccer_odds',
    match_ids: ['match_74021']
  }));
});

{
  "event_id": "odds_event_77192",
  "type": "odds_update",
  "match_id": "match_74021",
  "bookmaker_id": "bookmaker_12",
  "market_id": "market_match_winner",
  "selection_id": "home",
  "old_price": 1.84,
  "new_price": 1.76,
  "status": "open",
  "is_live": true,
  "updated_at": "2026-08-06T19:24:12Z"
}

processed_odds_events

event_id          unique
match_id
bookmaker_id
market_id
selection_id
old_price
new_price
processed_at

function isPriceStale(updatedAt, maximumAgeMs) {
  const updatedTime = new Date(updatedAt).getTime();

  if (!Number.isFinite(updatedTime)) {
    return true;
  }

  return Date.now() - updatedTime > maximumAgeMs;
}

{
  "market_id": "market_match_winner",
  "status": "settled",
  "settled_at": "2026-08-06T20:00:11Z",
  "outcomes": [
    {
      "selection_id": "home",
      "result": "won"
    },
    {
      "selection_id": "draw",
      "result": "lost"
    },
    {
      "selection_id": "away",
      "result": "lost"
    }
  ]
}

Soccer Odds API
       |
       v
Backend ingestion service
       |
       +-- Authentication
       +-- Market normalisation
       +-- Freshness validation
       +-- Duplicate protection
       +-- Historical snapshots
       |
       v
Internal odds store
       |
       +-- Sportsbook interface
       +-- Odds comparison page
       +-- Trading dashboard
       +-- Analytics pipeline
       +-- Affiliate widgets