API Basics

This page covers the practical basics shared by every Odds Comparison v2 package: how to authenticate, how request URLs are structured, the discovery feeds every integration starts with, pagination, and error handling. For the market payloads themselves, see Fundamentals.

Authentication

Every request is authenticated with your API key, sent in the x-api-key header. Your key is in your Sportradar developer account under your application's credentials; Make Your First Call covers creating an account and issuing a key.

GET https://api.sportradar.com/oddscomparison-prematch/trial/v2/en/books.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URLs and URL Structure

Each package is its own API with its own base URL. The path shape after the base URL is identical everywhere:

GET https://api.sportradar.com/oddscomparison-{package}/{access_level}/v2/{language_code}/{feed}.{format}

The common placeholders are access_level (trial or production), language_code (English, en, is the fully supported language), and format (json or xml). Both formats carry the same data on every feed; choose per your stack.

Odds Comparison API Map

One structure, four base URLs: each row is a package with its odds feeds, and the footer lists the feeds every package repeats.

ℹ️

One key, one configuration

Your key's bookmaker and coverage configuration applies across the packages it is entitled to. The Books feed on each package returns the bookmakers your key is configured for on that package.

The Discovery Feeds

Every package repeats the same small set of discovery feeds. A new integration walks them in order:

1. Books

Returns the bookmakers configured for your key, with the sr:book: ID used everywhere odds appear. This Prematch response also shows consensus, the calculated consensus line, delivered as a book of its own:

GET https://api.sportradar.com/oddscomparison-prematch/trial/v2/en/books.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-20T16:26:28+00:00",
  "books": [
    {
      "id": "sr:book:25080",
      "name": "consensus"
    },
    {
      "id": "sr:book:17324",
      "name": "MGM"
    },
    {
      "id": "sr:book:18149",
      "name": "DraftKings"
    },
    {
      "id": "sr:book:18186",
      "name": "FanDuel"
    },
    {
      "id": "sr:book:27447",
      "name": "BetRivers"
    },
    {
      "id": "sr:book:27769",
      "name": "PointsBet"
    },
    {
      "id": "sr:book:28901",
      "name": "Bet365.US.NJ"
    },
    {
      "id": "sr:book:32219",
      "name": "WilliamHillNewJersey"
    },
    {
      "id": "sr:book:40316",
      "name": "TheScore"
    }
  ]
}

<?xml version="1.0" ?>
<books xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.sportradar.com/sportsapi/oddscomparison-prematch/v2" generated_at="2026-07-20T16:30:07+00:00" xsi:schemaLocation="http://schemas.sportradar.com/sportsapi/oddscomparison-prematch/v2 https://schemas.sportradar.com/sportsapi/oddscomparison-prematch/v2/schemas/books.xsd">
  <book id="sr:book:25080" name="consensus"/>
  <book id="sr:book:17324" name="MGM"/>
  <book id="sr:book:18149" name="DraftKings"/>
  <book id="sr:book:18186" name="FanDuel"/>
  <book id="sr:book:27447" name="BetRivers"/>
  <book id="sr:book:27769" name="PointsBet"/>
  <book id="sr:book:28901" name="Bet365.US.NJ"/>
  <book id="sr:book:32219" name="WilliamHillNewJersey"/>
  <book id="sr:book:40316" name="TheScore"/>
</books>

2. Sports

Returns the sports the package can serve. Each sport carries a type of competition (league-structured sports such as baseball or soccer) or stage (tour-structured sports such as golf); competition sports are navigated through the Sport Competitions feed.

{
  "generated_at": "2026-07-20T16:30:09+00:00",
  "sports": [
    {
      "id": "sr:sport:1",
      "name": "Soccer",
      "type": "competition"
    },
    {
      "id": "sr:sport:2",
      "name": "Basketball",
      "type": "competition"
    },
    {
      "id": "sr:sport:3",
      "name": "Baseball",
      "type": "competition"
    },
    {
      "id": "sr:sport:4",
      "name": "Ice Hockey",
      "type": "competition"
    },
    {
      "id": "sr:sport:9",
      "name": "Golf",
      "type": "stage"
    },
    {
      "id": "sr:sport:16",
      "name": "American Football",
      "type": "competition"
    },
    {
      "id": "sr:sport:117",
      "name": "MMA",
      "type": "competition"
    }
  ]
}

3. Sport Competitions

Returns the competitions with odds available for a sport, each carrying three availability flags: markets (prematch markets), futures, and player_props. The flags tell you which package will have data for that competition before you make the call:

GET https://api.sportradar.com/oddscomparison-prematch/trial/v2/en/sports/sr:sport:3/competitions.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-20T16:30:12+00:00",
  "competitions": [
    {
      "id": "sr:competition:109",
      "name": "MLB",
      "gender": "men",
      "markets": true,
      "futures": true,
      "player_props": true,
      "category": {
        "id": "sr:category:16",
        "name": "USA",
        "country_code": "USA"
      }
    }
  ]
}

Sport Categories and Sport Stages feeds also exist on each package for category-scoped lookups (the Futures package uses categories directly; see Category Futures).

Pagination

List feeds return pagination headers on every response:

• X-Max-Results: total results available
• X-Offset: the offset the response starts at
• X-Result: the number of results in this response

Feeds that paginate accept start (offset) and, where supported, limit query parameters. The page size caps differ per feed and are enforced server-side:

Iterate by increasing start until X-Result comes back smaller than the page size (or 0). For example, an NFL Competition Futures response returns X-Max-Results: 90 with five markets per page; ?start=5 returns the next five.

Identifying Your Access Tier

Every response carries the X-Origin-Id header identifying the access tier serving your key:

• MARKET_ORIGIN_MAGIC_CRAWLERS: OC US
• MARKET_ORIGIN_CORE_CRAWLERS: OC Core

See the Overview for what the tiers cover.

Errors

• Authentication failures return 403 with an HTML body (an "Authentication Error" page), not a JSON error object, so branch on the status code rather than parsing the body:

GET https://api.sportradar.com/oddscomparison-prematch/trial/v2/en/books.json
x-api-key: (missing or invalid)

      <!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="utf-8">
          <title>Authentication Error</title>
        </head>
        <body>
          <p>Authentication Error</p>
        </body>
      </html>

• Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts.
• 404 indicates an unknown path or ID (for example, a sport event that does not exist in the package).
• The feeds otherwise use standard HTTP status codes; the Response Codes page lists them.

Time Values

All timestamps are UTC in ISO 8601 form (for example, "start_time": "2026-07-21T00:05:00+00:00"). Change log windows use Unix timestamps. A US evening game can carry the following day's UTC date; account for this when querying date-scoped feeds such as Daily Schedules.