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 / gives each event's state now, and GET / 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 (/). 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 toscheduled(returned) if venues list it pre-match again, as for a late or moved start; akickoffchange follows when the time moved.merged: a duplicate of the event inmerged_, always the final one.into 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 readsstartedafter its kick-off, and one called off inside K of kick-off readsstartedeither way.reasonisnullfor 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, orstartedwhen first seen in playkickoff: a new kick-off time;from_is the old onecommence_ time descriptors: a public field moved (previous_included);ids from_holds the old valuesdescriptors started,returned(back toscheduled) andmergedunmerged: a merge undone, so the id is its own fixture againregions: a region joined or left the event'sregions(regions_,added regions_), outsideremoved ukonlygoneandsplit(split_orto split_): not sent yetfrom
Snapshot, then follow
Walk every page of / with the region and filters you will use on /, and keep the first page's meta.since. A page holds up to 1,000 rows in id order; pass meta.next_ 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 / with the same region and filters. While meta.more is true, call again at once with meta.next_ (a page can be empty while more is true); then store meta.next_. 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 / 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.
# 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.
// 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 isscheduled, even when raw has no prices for it right now. - Hide it, but keep its row, while it is
started,goneormerged, and show it again when a later change makes itscheduled(returned,unmerged). - Take prices from
/with yourv2/ odds/ raw bookmakers, and never show them under an id whose state is notscheduled. Raw'smeta.removedreasonremoved, or a bookmaker leaving, means no prices now, never called off. When raw'sremoved_is later than yoursince updatedSince, read raw in full once. - On
merged, move your row and prices tomerged_. If you hold no row for it, fetch it withinto eventIds=and followmerged_until a row is notinto merged; if you filter/bychanges eventIds, add it there. Onunmerged, show the id by its own state and price it from raw under its own id. - A
scheduledrow 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_. An id raw serves appears here within 75 s. If an id is in unknown_ 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 (/ 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
scheduledwith no prices and readsstartedat its old kick-off plus K, and the new id arrives aslisted. A smaller move keeps the id and sendskickoff. - A restart of our matching can list an event again under a second id, for now. The old id stays
scheduledwith no prices until its kick-off plus K, unless we link the two withmerged. - Some fixtures are listed as two ids at different kick-offs, or at the same minute under two spellings. Both stay
scheduleduntil we link them or their own kick-off ends them. Twoscheduledids in one region with the samesport_, sides andkey commence_, only one of which raw serves, are one fixture: show the one raw serves.time - 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 /withoutchanges since. 400bad_: a malformedrequest since, an unknown or repeated parameter, a list inregion, orformat - 403
sport_: anot_ in_ plan sportsvalue outside your account's scope - 404
unknown_: a region the routes do not answer. For one you were reading, keep your rows andregion sinceand retry in 60 s - 410
since_: the log keeps 14 days, andexpired oldest_is its oldest point. Snapshot again, then look up withsince eventIdsevery 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_: retry with the sameunavailable since - While
meta.staleormeta.verdicts_is true, keep applying changes, and infer nothing from an event's absenceheld
Every parameter: API reference.