DocsGuidesView as Markdown

Regions

The region codes, what each region serves, one region per call, Global bookmakers, and what a prediction market's price means.

The codes

Every odds call takes a lowercase region code. GET /v2/regions lists the regions your key covers, each with its live bookmakers, its exchanges and its coverage_model: raw for a region that serves the raw board alone. GET /v2/bookmakers?region= lists one region's bookmakers and exchanges. These are the regions and what each serves:

What every region serves

Raw odds and event state are served in every region: Paging through raw odds and Following each event's state work the same way on any code. Each region has its own price table in GET /v2/pricing, and a call is priced from its region's: pricing shows each.

The matched products and the exchanges' lay prices are served in the UK & Ireland alone. Elsewhere, call raw: a matched product is not served there. A call there for any of them is refused with 403 product_not_in_region.

The sport key for football is soccer in every region. Our pages call the sport football, and soccer on the pages for the United States, Canada, Australia, South Africa and New Zealand.

A free quote for raw football in another region

curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/odds/raw?region=au&sports=soccer&quote=true"
# {"cost": …, "remaining": …, "rate_card": "…"}

Market names

Market keys are the same in every region, and they are not the names US sportsbooks print. A US name such as markets=moneyline, spreads or totals is refused with 400 unknown_market, and the reply lists the valid keys. Keyless GET /v2/coverage?region=us lists every market key the United States board carries.

Competitions have keys too, sent in sports: the NFL is american_football_nfl, the NBA basketball_nba, the NHL ice_hockey_nhl and MLS soccer_mls. GET /v2/sports?region=us lists the rest. A league with no games on the board, out of season for example, can be missing from that list until its games return.

Add oddsFormat=american for American prices: Converting to American odds says which routes take it. Paging through raw odds covers how outcomes are named.

The keys to send for the US names:

  • Moneyline: h2h
  • Spread: handicap
  • Total: over_under
  • Player props: the keys that start player_, such as player_points, player_rebounds, player_passing_yards and player_touchdowns

NFL moneyline, spread and total at American prices

curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/odds/raw?region=us&sports=american_football_nfl&markets=h2h,handicap,over_under&oddsFormat=american"

One region per call

A key reads every region. Each call names one region, and its tokens come from that region's price table (raw alone takes several international codes at once: see Global bookmakers below). The region you chose at sign-up is where your dashboard opens: it does not limit your key.

A key can be narrowed to chosen regions, and an Enterprise contract names its regions. A call outside them is refused with 403 region_not_in_scope.

Prediction markets

Prediction markets are served as bookmakers. An outcome's price is the decimal form of the best ask, 1 divided by the ask, before the market's fees. A prediction market carries no lay price and is never a leg of a dutching set.

Its row on GET /v2/bookmakers can carry fee_model, the market's fee formula: apply it to work out what a taker receives.

Global bookmakers

Pinnacle and the other bookmakers with no one country are a region of their own, global, asked with region=global. A call for a country's code does not return them. GET /v2/odds/raw takes several international codes in one call, region=us,global, priced as those codes' prices added together. The reply is one board, each event once with every listed region's rows: meta.region is the codes sorted and joined by commas, global,us, and meta.regions the same codes as an array. The UK & Ireland is asked alone, and every other route takes one code. The dashboard lists the Global bookmakers under every international region while "Include Global bookmakers", beside its region list, is on.

With the UK & Ireland, or on any other route, to compare them with a country's books, call both regions and join the two answers on the event id. The two calls share an event's id wherever the two listings can be matched, as the next section says.

Event ids across regions

A match that uk lists has the same event id on every other region wherever the two listings can be matched. An older id that was merged into it keeps working and is listed in previous_ids. Racing, outrights, virtual games and matches that two regions list too differently keep their own region's id. since tokens belong to one lane: uk, or every other region together. An event's competition_key can differ between uk and another region.

Stable event ids covers what names an event and the ids merged into another.

How fresh the prices are

Outside the UK & Ireland, prices are read less often than on the UK board, so a price can be older when it reaches you. Every price carries its own times: How fresh a price is shows how to work out its age.

Every parameter: API reference.