What is an odds API? A 2026 guide for builders
OddsRelay · · Updated · 5 min read
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 JSON back: events, markets, outcomes and the price each bookmaker is offering on them. (The glossary entry has the one-line version.)
What does an odds API actually return?
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.
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 walks through a first call.
Raw odds API or matched feed?
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):
{
"id": "or_evt_da71d5873e85",
"sport_key": "soccer_epl",
"sport_title": "Premier League",
"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 enough for an odds-comparison table. 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:
{
"event_id": "or_evt_917dd44bce05",
"sport_key": "soccer_epl",
"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": "betfair_exchange", "price": 3.0, "available": 175, "link": null }]
}]
}]
}Each lay offer carries available, the money on offer at that price. OddsRelay's matched boards are paired against exchange lay and liquidity-gated. The rating and qualifying loss are simple arithmetic on the pair, done at your own commission rate, and the oddsmatcher widget shows them:
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 odds API vs odds feed weighs it.
Pull or push? 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 weighs the trade-off.
OddsRelay is pull only and built for pre-match data. There is no in-play product, and nothing is pushed: 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 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 explains each timestamp, raw's included.
What should you evaluate before choosing one?
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 shows each venue and sport as live or interrupted.
- Lay support: are back prices paired with an exchange lay price and its liquidity? OddsRelay's lay side comes from Betfair, Smarkets, Matchbook and BETDAQ.
- Freshness: does every response tell you how old its prices are, and is there a stated bound? Every OddsRelay product on sale meets a maximum update time of 10–20 s.
- Cost per call: is the price of a request knowable before you send it? On OddsRelay it comes from the board and filters you ask for, never the response size, and
?quote=trueprices a call without spending. Filters and tokens has the detail.
Our view is that every one of these should be checkable from outside before you sign anything. For a structured way to weigh them against each other, see how to choose an odds data provider.
Where does an odds API fit in what you're building?
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, consistent names, a timestamp per market | Raw is enough. 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 |
| Tipster or content site | Best prices for a handful of fixtures, cheaply | Raw is usually enough |
On OddsRelay the choice is not a plan decision. Raw and the six matched boards are on every plan, and plans differ only in tokens. If you would rather source prices yourself, how to get bookmaker odds data sets out the realistic routes and their trade-offs.
Make a first call
The contract, with real example responses, is in the API reference. To make calls against the live feed, request access, or see live coverage first.