DocsGuidesView as Markdown

Following each event's state

Whether each event is still on, from two free routes: the snapshot, the log of changes, the recipe for a listing and the windows behind started.

What the two routes say

GET /v2/events/state gives each event's state now, and GET /v2/events/changes gives every change since a point you hold, in order. The state is the fixture's, judged across every bookmaker and exchange we read, not only yours: an event your bookmakers stop pricing stays scheduled while it is on.

Whether your bookmakers price an event is raw's answer (/v2/odds/raw?bookmakers=). Build your listing from raw, and use these two routes for each event's fate.

Both cost 0 tokens, need a key and count against your account's rate limits. They answer in the envelope only, so format is a 400.

The states

Every row carries one state:

  • scheduled: not known to be over or called off. It may have no prices right now: raw answers that.
  • started: pre-match is over, because it was seen in play, or its kick-off plus K (the windows below) passed with no venue listing it pre-match. It is not a claim the event was played. It returns to scheduled (returned) if venues list it pre-match again, as for a late or moved start; a kickoff change follows when the time moved.
  • merged: a duplicate of the event in merged_into, always the final one.
  • gone: called off before kick-off by every venue that listed it, confirmed. It is not sent yet, and the changelog will give the date it starts. Until then a called-off event reads started after its kick-off, and one called off inside K of kick-off reads started either way. reason is null for now.

The changes

Each change carries seq, at, change and the event's whole row in event. change is one of:

  • listed: first seen, scheduled, or started when first seen in play
  • kickoff: a new kick-off time; from_commence_time is the old one
  • descriptors: a public field moved (previous_ids included); from_descriptors holds the old values
  • started, returned (back to scheduled) and merged
  • unmerged: a merge undone, so the id is its own fixture again
  • regions: a region joined or left the event's regions (regions_added, regions_removed), outside uk only
  • gone and split (split_to or split_from): not sent yet

Snapshot, then follow

Walk every page of /v2/events/state with the region and filters you will use on /changes, and keep the first page's meta.since. A page holds up to 1,000 rows in id order; pass meta.next_cursor as cursor for the next one (there is no X-Next-Cursor header, and a cursor expires 300 s after it was issued). Store each row with its seq.

states defaults to scheduled. Any other value needs eventIds, or a kick-off window of at most 7 days. eventIds, at most 50, is one page in all four states: each id's own row, plus the final event each merged id became, whatever your filters. Look up every id raw serves that your snapshot lacks this way.

Then, every ~30 s, call /v2/events/changes?since= with the same region and filters. While meta.more is true, call again at once with meta.next_since (a page can be empty while more is true); then store meta.next_since. A call returns up to 1,000 changes by default, 5,000 at most.

Use the snapshot's filters exactly. A kick-off window on /changes selects on the event's kick-off at the time of each change, so an event that enters a moving window as time passes sends no change: fix the window and snapshot again to move it, or filter on your side.

Snapshot, look up, follow

# 1. Snapshot: every scheduled football event, a page at a time; keep the FIRST page's meta.since
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/state?region=uk&sports=soccer"

# 2. Any ids you hold, at most 50, in all four states: a merged id also returns the event it became
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/state?region=uk&eventIds=$EVENT_IDS"

# 3. Every ~30 s: what changed since, with the snapshot's region and filters; keep meta.next_since
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events/changes?region=uk&sports=soccer&since=$SINCE"

Applying changes

For every change whose seq is above the seq of the row you hold, or for an id you hold no row for, replace your row with the change's event, whatever its change value, including values you do not know yet. Applying one twice is harmless: the highest seq wins.

If raw serves an id the changes have not named within 2 minutes, look it up with eventIds.

Follow the log

// state: Map of event id -> row, from your snapshot. since: the snapshot's first meta.since.
// get(path): your keyed GET, returning the parsed reply.
async function follow(state, since, query) {
  for (;;) {
    const page = await get(`/v2/events/changes?${query}&since=${since}`);
    for (const c of page.data) {
      const held = state.get(c.event.id);
      if (!held || c.seq > held.seq) state.set(c.event.id, { ...c.event, seq: c.seq });
    }
    since = page.meta.next_since;
    if (!page.meta.more) return since; // store it; call again in ~30 s
  }
}

Listing from raw

  • Add an event to your listing when raw serves it with your bookmakers, and keep it while its state is scheduled, even when raw has no prices for it right now.
  • Hide it, but keep its row, while it is started, gone or merged, and show it again when a later change makes it scheduled (returned, unmerged).
  • Take prices from /v2/odds/raw with your bookmakers, and never show them under an id whose state is not scheduled. Raw's meta.removed reason removed, or a bookmaker leaving, means no prices now, never called off. When raw's removed_since is later than your updatedSince, read raw in full once.
  • On merged, move your row and prices to merged_into. If you hold no row for it, fetch it with eventIds= and follow merged_into until a row is not merged; if you filter /changes by eventIds, add it there. On unmerged, show the id by its own state and price it from raw under its own id.
  • A scheduled row whose kick-off has passed is not yet confirmed started: a pre-match listing hides it at its own cut-off and keeps the row.

Which events are covered

The routes cover every id raw serves in the region; an id only a matched board serves comes back in meta.unknown_ids. An id raw serves appears here within 75 s. If an id is in unknown_ids while this reply's X-OddsRelay-Version is below the raw page's, it is not recorded yet: ask again. If it is still unknown after that, it is not tracked yet (a new listing in its first minute, a race in its first 10 minutes, or a race of fewer than 2 runners): ask again in 60 s, and treat it as scheduled from raw meanwhile.

region is one code, never a list, read as raw reads one: uk when missing, and every region raw serves (/v2/regions lists yours). since tokens belong to one lane, uk or every other region. A fixture listed in both can have a row in each, and the two can briefly differ, so keep one state store and one since per region you read.

An event belongs to every region whose reply lists it, for its whole life: show it there while it is scheduled. regions says where venues listed it in the last 30 minutes (always ["uk"] in uk), so never hide an event because a code left regions.

Duplicates and new ids

  • A fixture moved by more than its sport's match window and 12 h can take a new id with no link, for now. The old id stays scheduled with no prices and reads started at its old kick-off plus K, and the new id arrives as listed. A smaller move keeps the id and sends kickoff.
  • A restart of our matching can list an event again under a second id, for now. The old id stays scheduled with no prices until its kick-off plus K, unless we link the two with merged.
  • Some fixtures are listed as two ids at different kick-offs, or at the same minute under two spellings. Both stay scheduled until we link them or their own kick-off ends them. Two scheduled ids in one region with the same sport_key, sides and commence_time, only one of which raw serves, are one fixture: show the one raw serves.
  • Never join two ids at different kick-offs yourself: doubleheaders, series and rematches are different fixtures. We link true duplicates with merged.
  • A placeholder side renamed (Qualifier to a player), or a race whose field changed, can take a new id; show the one raw serves. Raw can still carry one venue's row with a wrong date under an id: trust the state.

The windows

K: a pre-match listing that ends this close to kick-off counts as the kick-off. G: the grace after kick-off used to confirm. C: the most we wait for a venue still listing an event. They are floors for now, and measured values per sport will replace them from a date the changelog gives, so treat when an event reads started as something that can change.

  • Football, handball, rugby union, rugby league, American football, ice hockey, basketball and volleyball: K 15 min, G 60 min, C 60 min
  • Baseball and cricket: K 15 min, G 4 h, C 3 h
  • Tennis and badminton: K 15 min, G 2 h, C 6 h
  • Table tennis: K 10 min, G 1 h, C 3 h
  • Darts and snooker: K 15 min, G 2 h, C 4 h
  • MMA and boxing: K 15 min, G 3 h, C 8 h
  • Esports: K 15 min, G 2 h, C 2 h
  • Golf matchups: K 15 min, G 3 h, C 4 h
  • Any other sport but racing: K 15 min, G 60 min, C 60 min
  • Horse and greyhound racing: K 15 min, for an abandonment mid-card only

Errors and flags

  • 400 missing_param: /changes without since. 400 bad_request: a malformed since, an unknown or repeated parameter, a list in region, or format
  • 403 sport_not_in_plan: a sports value outside your account's scope
  • 404 unknown_region: a region the routes do not answer. For one you were reading, keep your rows and since and retry in 60 s
  • 410 since_expired: the log keeps 14 days, and oldest_since is its oldest point. Snapshot again, then look up with eventIds every id you hold that the new snapshot lacks before you hide it
  • 429: your account's rate limit; wait the Retry-After seconds
  • 503 temporarily_unavailable: retry with the same since
  • While meta.stale or meta.verdicts_held is true, keep applying changes, and infer nothing from an event's absence

Every parameter: API reference.