# What is an odds API?

> An odds API returns bookmakers' prices as structured data your software can read. What one returns, raw versus matched feeds, and what to check first.

Published 1 July 2026 · updated 5 November 2026

**An odds API hands your software bookmakers' prices as structured data, so no person has to read betting sites by hand: your code sends a keyed request and gets back JSON listing events, markets, outcomes and each bookmaker's price.** The [glossary entry](https://oddsrelay.io/glossary/odds-api) has the one-line version, and [odds API vs sports data API](https://oddsrelay.io/blog/odds-api-vs-sports-data-api) separates it from feeds of scores and statistics.

## What an odds API returns

It returns the structure of a betting market. A football match is an **event**, with an id, two teams and a kick-off time. Its match-odds market holds one **outcome** per result. Each outcome carries a decimal price, and each price is tagged with the bookmaker offering it. [Football odds data, explained](https://oddsrelay.io/blog/football-odds-data-explained) walks through the markets a match carries. [Our study of UK bookmaker margins](https://oddsrelay.io/blog/uk-bookmaker-margins-study) compares how much margin each bookmaker builds into those prices.

The metadata is what makes a price usable. A price with no bookmaker and no timestamp is a number you cannot reason about. A price that says which venue offered it, and when that venue was last read, is data you can build on.

Calling one is an authenticated HTTP request. You send a key (in the `Authorization: Bearer` header, for OddsRelay), you narrow the request with filters such as sport, bookmaker or market, and JSON comes back. The [quickstart](https://oddsrelay.io/docs/guides/quickstart) walks through a first call.

## Odds API vs odds feed

An odds API and an odds feed mostly name one product from two angles, so choosing between them is a naming question. What changes your build is whether the prices arrive raw or already matched.

- **API** is the interface word. It names the contract: the endpoint you call, the parameters you pass and the JSON shape you get back.
- **Feed** is the supply word. It names the promise that someone keeps the data maintained and refreshed over time. The [odds feed glossary entry](https://oddsrelay.io/glossary/odds-feed) has the precise sense.

A vendor leaning on "API" is usually advertising a clean integration, and one leaning on "feed" is usually advertising upkeep. How the data reaches you is a third question, and either kind can be polled, so settle which data you need first.

## Raw prices or matched data

The biggest difference between odds APIs is how much processing they have done before you receive the data. A **raw** API hands you each bookmaker's prices as it found them. A **matched** feed pairs prices for you, most often a bookmaker back price with an exchange lay price for the same outcome, so the two sides of a matched bet arrive together.

A raw event lists the bookmakers, each with its markets and a per-market `last_update` (when that market last changed). Here it is trimmed to one bookmaker, with the event's `sport_key` and `sport_title` left out:

Raw event, trimmed · example:

```json
{
  "id": "or_evt_917dd44bce05",
  "commence_time": "2026-09-20T14:00:00Z",
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "bookmakers": [{
    "key": "william_hill",
    "title": "William Hill",
    "region": "uk",
    "last_update": "2026-09-20T12:18:09Z",
    "markets": [{
      "key": "h2h",
      "last_update": "2026-09-20T12:17:02Z",
      "outcomes": [{ "name": "Arsenal", "price": 2.9 }, { "name": "Chelsea", "price": 2.5 }]
    }]
  }]
}
```

That is the starting point for an odds-comparison table, once your code lines up each venue's own names for the outcomes. It is not enough for matched betting, which runs on a relationship between two prices: the bookmaker back price and the exchange lay price for the same outcome. A matched board carries both sides on each outcome:

Matched event, one outcome, trimmed · example:

```json
{
  "event_id": "or_evt_917dd44bce05",
  "commence_time": "2026-09-20T14:00:00Z",
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "markets": [{
    "key": "h2h",
    "outcomes": [{
      "name": "Arsenal",
      "back": [{ "bookmaker": "william_hill", "price": 2.9, "link": null }],
      "lay":  [{ "exchange": "smarkets", "price": 3.0, "available": 175, "link": null }]
    }]
  }]
}
```

Each `lay` offer carries `available`, the liquidity on offer at that price, and OddsRelay leaves a lay off its matched boards when too little liquidity sits behind it. Your code works out the rating from the two prices at your own commission rate, and the [oddsmatcher widget](https://oddsrelay.io/widgets/oddsmatcher) shows the same sums:

Your side of the pair · example:

```ts
const back = 2.9;  // bookmaker back price
const lay = 3.0;   // exchange lay price
const rating = (back / lay) * 100; // 96.7
```

Building the pairing yourself means an exchange integration and a matcher that knows two venues' names for one event are the same event, on top of collecting the prices. That build is the real decision, and [buying vs building an odds data layer](https://oddsrelay.io/blog/buy-vs-build-odds-data) weighs it.

## How the data reaches you

There are two delivery models. With pull, your software asks for the latest board when it wants one. With push, a vendor sends each change to you over a webhook or an open connection. Push suits a live event where every movement matters. Pull suits pre-match data, where your application decides how often it needs a fresh view. [Webhooks vs polling for odds data](https://oddsrelay.io/blog/polling-an-odds-feed-efficiently) weighs the trade-off.

OddsRelay's self-serve plans are pull only, for pre-match prices and, since 2 November 2026, in-play prices on raw and on the standard and dutching boards, as [live vs pre-match odds data](https://oddsrelay.io/blog/live-vs-pre-match-odds-data) explains. Nothing is pushed on a self-serve key: no webhook, no stream. Every data reply carries an `ETag`: send it back as `If-None-Match` and an unchanged board comes back as a `304`, which costs no tokens. The [conditional requests guide](https://oddsrelay.io/docs/guides/conditional-requests) covers the pattern.

Whichever model a vendor uses, ask how you can tell the age of a price in hand. On OddsRelay every response carries the board time, `meta.processed_at` (or the `X-Processed-At` header), the time the board was built. A matched board adds `meta.last_seen` per venue and sport, the last time that venue was read, so now minus it is an upper bound on a price's age. The [freshness guide](https://oddsrelay.io/docs/guides/freshness) explains each timestamp, raw's included.

## What to check before choosing

These are the places where odds APIs differ, and where a gap costs you later:

- **Coverage**: which books, in which region, and can you check it today? OddsRelay covers 140+ bookmakers, 60+ of them live in the UK & Ireland, bet365 included, and the [coverage page](https://oddsrelay.io/coverage) lists every venue and the sports it is covered on.
- **Lay support**: are back prices paired with an exchange lay price and its liquidity? OddsRelay's lay side comes from Betfair, Smarkets and Matchbook.
- **Freshness**: does every response tell you how old its prices are, so you can check a price's age yourself?
- **Cost per call**: is the price of a request knowable before you send it? On OddsRelay's live feed it comes from the board and filters you ask for, never the response size, and `?quote=true` prices a call without spending. [Filters and tokens](https://oddsrelay.io/docs/guides/filters-and-tokens) has the detail.

Our view is that every one of these should be checkable from outside before you sign anything, which is most of what [responsible data supply](https://oddsrelay.io/blog/responsible-data-supply-for-betting-products) means. For a structured way to weigh them against each other, see [how to choose an odds data provider](https://oddsrelay.io/guides/how-to-choose-an-odds-data-provider).

## Which products need which data

Three kinds of product lean on an odds API, and each wants a different level of processing:

| Product | What it needs from the API | Raw or matched? |
| --- | --- | --- |
| Odds comparison | Many books, a timestamp per market | Raw, plus your own name matching. Coverage and freshness decide it |
| Oddsmatcher or matched-betting tool | Back price paired with an exchange lay price and its liquidity | Matched. The qualifying bet is the back and lay pair |
| Betting content site | Best prices for a handful of fixtures, cheaply | Raw is usually enough |

[How odds comparison sites use data](https://oddsrelay.io/blog/how-odds-comparison-sites-use-data) takes the first row further. On OddsRelay the choice is not a plan decision. Raw, the six matched boards and [historical odds](https://oddsrelay.io/products/historical-odds), the bookmakers' and exchanges' past prices since 17 October 2026, are on every self-serve plan, and those plans differ only in tokens. Who uses the data decides the plan instead: the paid self-serve plans are for personal use, and a business, or any of these products shown to other people, runs on [Enterprise](https://oddsrelay.io/enterprise). If you would rather source prices yourself, [how to get bookmaker odds data](https://oddsrelay.io/blog/how-to-get-bookmaker-odds-data) sets out the realistic routes and their trade-offs.

## Make a first call

Read the contract and its example responses in the [API reference](https://oddsrelay.io/docs/reference), check your bookmakers on [the coverage page](https://oddsrelay.io/coverage), then price one call with `quote=true` before you make it.

18+ · OddsRelay supplies odds data only and takes no bets. Please gamble responsibly.

Source: https://oddsrelay.io/blog/what-is-an-odds-api