API docs

Version 1. Every response is JSON.

Get a free API key

Pre-match odds from UK, US and (soon) South African bookmakers, with each game matched across bookmakers and every price change kept.

Base URL: https://api.oddsgator.io

Authentication

Every /v1 call needs an API key, sent as a header:

x-api-key: <your key>

Authorization: Bearer <your key> and ?apiKey=<your key> work too. A missing or wrong key gets a 401.

Get a key at oddsgator.io: create an account, confirm your email, and create keys in the dashboard. A key is shown once, when you create it; if you lose it, revoke it and create another.

Limits

Each plan has a number of requests a month (the free plan: 500), shared by all your keys. Only successful requests count. Every response says where you are:

x-requests-used: 42
x-requests-remaining: 458

Over the limit, requests get a 429 until the first of the next month (UTC). The dashboard shows your usage by day and by key.

Conventions

  • Times are ISO 8601 in UTC (2026-11-15T21:10:00.000Z).
  • Responses are JSON objects with a data field. Errors are {"error": "..."} with a 4xx/5xx status.
  • Bookmaker ids are <brand>-<country>, with ISO country codes: betway-gb is Betway in the UK, draftkings-us is DraftKings in the US, betway-za is Betway in South Africa.
  • Prices are decimal odds, with American odds worked out from them and fractional odds where the bookmaker shows them (mostly UK): {"decimal": 2.36, "american": 136, "fractional": "11/8"}. A selection listed without a price has "price": null.
  • Freshness: every bookmaker carries lastUpdate, when its prices were collected. A bookmaker with no snapshot in the last 30 minutes is stale, and its prices are left out unless you add includeStale=true. Games leave /v1/events at kick-off: prices are pre-match only.

Sports and markets

sport Competitions (examples)
football Premier League, Championship, La Liga, Champions League
american_football NFL, NCAAF
basketball NBA, NCAAB
ice_hockey NHL
baseball MLB (in season)
Market type Selections (outcome) line
match_result home, draw, away
moneyline home, away
spread home, away Points from the home team's side: −6.5 means home favoured by 6.5
total, total_goals over, under The points or goals line
both_teams_to_score yes, no
double_chance home_draw, home_away, draw_away
draw_no_bet home, away
outright other (the selection's name says who)
other other The market's name says what it is

home and away always follow the event's home and away, even when a bookmaker lists the game the other way round.

Endpoints

GET /v1/sports

Sports and competitions with upcoming games.

{ "data": [ { "sport": "basketball", "events": 64, "competitions": [ { "name": "NBA", "events": 41 }, { "name": "NCAAB", "events": 23 } ] } ] }

GET /v1/bookmakers

Every bookmaker, with its freshness and last failure.

{ "data": [ { "id": "draftkings-us", "name": "DraftKings", "country": "us", "lastUpdate": "2026-11-15T20:25:39.004Z",
              "stale": false, "events": 212, "lastFailure": null } ] }

GET /v1/events

Upcoming games with every bookmaker's current prices, soonest first.

Parameter Default
sport all e.g. basketball
competition all e.g. NBA (case-insensitive)
bookmakers all Comma-separated ids, e.g. draftkings-us,betmgm-us
markets all Comma-separated types, e.g. moneyline,spread
from, to now, 14 days Kick-off window
limit, offset 100, 0 Up to 500 per page
includeStale false Include stale bookmakers' prices
{
  "data": [
    {
      "id": "phoenix-suns-vs-los-angeles-lakers-2026-11-15",
      "sport": "basketball",
      "competition": "NBA",
      "home": "Phoenix Suns",
      "away": "Los Angeles Lakers",
      "startTime": "2026-11-15T21:10:00.000Z",
      "bookmakers": [
        {
          "bookmaker": "draftkings-us",
          "name": "DraftKings",
          "lastUpdate": "2026-11-15T20:25:39.004Z",
          "url": "https://sportsbook.draftkings.com/event/33416781",
          "markets": [
            { "type": "moneyline", "name": "Moneyline", "line": null, "selections": [
                { "outcome": "away", "name": "LA Lakers", "price": { "decimal": 1.621, "american": -161 }, "suspended": false, "changedAt": "2026-11-15T19:02:11.000Z" },
                { "outcome": "home", "name": "PHO Suns", "price": { "decimal": 2.36, "american": 136 }, "suspended": false, "changedAt": "2026-11-15T19:02:11.000Z" } ] },
            { "type": "spread", "name": "Spread", "line": 3.5, "selections": [ "…" ] }
          ]
        }
      ]
    }
  ],
  "meta": { "limit": 100, "offset": 0, "count": 1 }
}

name is the selection as the bookmaker writes it; outcome is what it means. changedAt is when the price last changed. suspended: true means the price is listed but can't be bet right now.

GET /v1/events/{id}

One event, in the same shape. Takes bookmakers, markets and includeStale.

GET /v1/events/{id}/history

Every price change for an event: one series per bookmaker and selection, oldest first. Takes bookmakers and markets.

{
  "data": {
    "event": { "id": "phoenix-suns-vs-los-angeles-lakers-2026-11-15", "…": "…" },
    "series": [
      { "bookmaker": "draftkings-us", "market": "moneyline", "marketName": "Moneyline", "line": null, "outcome": "home", "name": "PHO Suns",
        "points": [ { "at": "2026-11-14T09:30:02.000Z", "decimal": 2.45, "suspended": false },
                    { "at": "2026-11-15T19:02:11.000Z", "decimal": 2.36, "suspended": false } ] }
    ]
  }
}

A point is recorded only when the price or its suspended flag changes, so a price holds until the next point. A point with "removed": true marks when the bookmaker stopped listing the selection (usually at kick-off): its last price before that is the closing price.

Errors

Status Meaning
400 A parameter is invalid; error says which
401 Missing or invalid API key
404 No such event
429 This month's requests are used up: error says when they reset
5xx Our problem: retry with backoff