How bookmaker odds data is structured

Bookmaker odds data is a hierarchy: an event holds one or more markets, each market holds selections, and each selection carries a price. Wrapped around that are metadata fields: which bookmaker, which region, and when the price was last seen. Once that four-level shape clicks, the rest of integration is straightforward, because every odds payload you will ever read is a variation on the same nesting.

This post walks each level with concrete examples, explains how decimal prices update, and shows how a matched feed extends the model with a lay side from an exchange. For the field-by-field tour of a real response, pair it with the anatomy of a response; for the broader concept, what an odds API is.

What are the levels in odds data?

There are four, nested from outside in. Each level answers a single question, and nothing belongs at the wrong level:

• Event: the thing being bet on. A football match such as Arsenal vs Chelsea, a race, a tournament outright. The event carries identity and timing, not odds.
• Market: a question about the event with a fixed set of answers. match_odds (home, draw, away), over_under_2_5, both_teams_to_score. One event has many markets.
• Selection: one answer within a market. Arsenal inside match_odds; over inside over_under_2_5; yes inside both_teams_to_score. A market is a list of selections.
• Price: the odds attached to a selection, as a decimal number such as 2.10. This is the leaf of the tree, and the level that changes second to second.

Read it as a sentence: for this event, in this market, this selection is priced at this number. Everything else in a payload is metadata describing where that number came from and how fresh it is.

How do the levels look in practice?

Take one match. The match_odds market has three selections, the over_under_2_5 market has two, and both_teams_to_score has two. Same event, different questions, each with its own selections and prices:

{
  "event": "Arsenal vs Chelsea",
  "markets": [
    {
      "market": "match_odds",
      "selections": [
        { "selection": "Arsenal", "back": { "bookmaker": "bet365", "odds": 2.10 } },
        { "selection": "Draw",    "back": { "bookmaker": "bet365", "odds": 3.40 } },
        { "selection": "Chelsea", "back": { "bookmaker": "bet365", "odds": 3.60 } }
      ]
    },
    {
      "market": "over_under_2_5",
      "selections": [
        { "selection": "over",  "back": { "bookmaker": "bet365", "odds": 1.91 } },
        { "selection": "under", "back": { "bookmaker": "bet365", "odds": 1.95 } }
      ]
    }
  ]
  // ... region, timestamp and further markets elided
}

Nothing here is specific to one bookmaker. The same Arsenal selection in match_odds appears under every book that prices the match, each with its own back odds. That uniformity is what lets a feed carry 60+ UK books, bet365 included, behind one consistent shape.

What are the prices and how do they update?

Prices are decimal odds: the total return per unit staked, including the stake. 2.10 returns 2.10 for every 1 staked. Decimal is the format a feed standardises on because it sorts and compares cleanly, unlike fractional odds. Every selection carries exactly one back price per bookmaker.

Prices change as a bookmaker moves its book. A selection at 2.10 may be 2.05 a minute later, while the rest of the event holds steady. A feed refreshes these on a cadence: our honest posture is pre-match polling on roughly a few-second cycle, which suits pre-match work well. So a price is always a price as last seen, never a guaranteed live quote. That is why freshness metadata matters as much as the number.

What metadata travels with each price?

Three fields turn a bare number into something you can trust and route:

• Bookmaker: which book the price belongs to, as a stable slug such as bet365 or williamhill. Identity, so you can group, compare and filter by book.
• Region: which market the book serves, such as uk. This lets one event fan out to region-specific feeds, including emerging-market books like South African and Nigerian books that the big aggregators skip.
• Freshness: a timestamp for when the price was last seen. A stale price looks usable and isn't, so this field is what separates a real feed from a snapshot.

Together these are the odds-feed contract: a stream of priced selections, each tagged with its book, its region and its freshness. The full definition sits in the odds feed definition.

How does matched data extend the model?

A matched feed keeps the same hierarchy and adds a lay side. The bookmaker price becomes the back, and alongside it sits the current exchange lay price for the same selection, drawn from one of three exchanges (Betfair, Smarkets, Matchbook). The pairing is the part that makes the data usable for matched betting and arbitrage, because an opportunity is a relationship between two prices, not a single number.

Two computed fields ride on top of that pair. rating scores how close the back and lay prices are, and qualifying_loss is the small expected loss on a qualifying bet. Both are derived from the back/lay relationship, so they only exist once matching has been done. Here is the same Arsenal selection with the lay side added:

{
  "event": "Arsenal vs Chelsea",
  "market": "match_odds",
  "selection": "Arsenal",
  "back": { "bookmaker": "bet365", "odds": 2.10 },
  "lay":  { "exchange": "betfair", "odds": 2.14, "liquidity": 1840 },
  "rating": 98.1,
  "qualifying_loss": -0.12
  // ... region, feed_type and freshness fields elided
}

The liquidity figure on the lay block tells you how much can actually be matched at that price, so the lay is real rather than notional. For why the back and lay sides behave differently, read back and lay odds explained. The full envelope, with every field named, is in the API docs.

Why the shape matters before you integrate

Once the hierarchy is clear, integration is mechanical. You request odds, walk events to markets to selections, and read each price with its metadata. If the feed is matched, you also read the paired lay, the rating and the qualifying loss, and render results without building a matcher yourself. The data model is small on purpose, so the same handful of fields cover every event and market.

If you want to see the shape against live data rather than an illustrative sample, the fastest path is a free trial: you get the full UK feed, bet365 included, matched against exchange lay prices. It powers a leading UK matched-betting platform today, and you can check what is live on the coverage dashboard before you commit.