DocsGuidesView as Markdown

Stable event ids

One id per event, what names an event, which fields stay as first served, ids merged into another, course names and the catch-all sport keys.

One id per event

Every event has one id, opaque and the same on every route: raw, the event route, /v2/events, the matched boards and historical odds. It is kept for as long as the event is served, so it is the key to store.

When two ids turn out to be one fixture, the id served first is kept and the other is listed in that event's previous_ids, on every route that serves it: /v2/odds/raw, /v2/odds/event/{id}, /v2/events and, since 14 November 2026, the matched boards, where it comes after competition_key. previous_ids never holds the event's own id.

A merged id still answers on /v2/odds/event/{id} and in eventIds with the event it became while that event is on the board, and again if its fixture is listed again within 60 days. Once that event has left the board, both ids answer 404 unknown_event on /v2/odds/event/{id} and return no event in eventIds, and historical odds still serve both. On a raw updatedSince walk, a merge shows in meta.removed with the reason merged and the surviving id in merged_into: Paging through raw odds covers it.

What names an event

Since 13 November 2026, every event names itself on every route, in one of three ways:

  • A team fixture: home_team and away_team. Home and away never swap while a bookmaker lists them in that order.
  • A race, horse or greyhound: venue, the course, such as Cheltenham or Doomben (AUS). Its home_team and away_team are null on raw, the event route and /v2/events, and left out on the matched racing boards.
  • Any other event with no two teams, such as a golf tournament, an outright or a special: event_name, such as The Masters 2027.

Races and outrights

venue and event_name come after the teams (after commence_time on a matched race, which has no team fields), and each appears only on the events it names. An ante-post market carries its festival's course in venue, or none, and its category in event_name, such as Ante-Post National Hunt.

On the matched boards that list greyhound races (standard), a race also keeps the event_name it was first served with, its UK off time and course (21:04 Central Park), beside venue. Raw, the event route and /v2/events serve a race's venue alone.

To show a race, venue and commence_time name it; to show an outright, event_name does.

What stays as first served

An event keeps the sport_key, sport_title and competition_key it was first served with, on every route, for as long as it is served. A null competition_key can gain a key once; after that the key never changes for the event, and a key is never renamed or reused.

Teams, venue and event_name stay as first served while a bookmaker still lists the event that way. The one field that moves is commence_time: when a fixture is rescheduled, it follows the exchange where one lists the event, else most bookmakers.

When these rules came in, on 13 and 14 November 2026, some events' values were corrected once and then held. The changelog lists the corrections.

Course names

venue is one string per course on every route, historical odds included. A UK or Irish course is plain: Cheltenham, Towcester. An overseas course carries a country tag, one spelling per country, such as (AUS), (NZL), (JPN) or (CAN): Doomben (AUS), Woodbine (CAN). A greyhound track is named without its meeting's words: Hove.

A course new to the feed can appear untagged until it is added, so a plain venue is not proof of a UK or Irish course.

Sport and competition keys

sport_key is the sport and the league its bookmakers file the event under: soccer_premier_league for a Premier League match (its competition_key is soccer_english_premier_league, the key to send for the Premier League), and horse_racing for a horse race. An event whose bookmakers name no competition is served under its sport's catch-all key, the sport's name twice, such as golf_golf, tennis_tennis, cricket_cricket and greyhound_racing_greyhound_racing.

A catch-all sport_key can still carry a named competition_key, so pick out a competition by competition_key. It is null on every racing event, and usually on an event whose bookmakers' names for it identify no one competition (golf's catch-all events carry golf_golf).

A competition known under several keys comes back whole: sports= with any of its keys returns every event of it, on every route. New events carry one key for it, and an event already served keeps its own.

Looking an event up

GET /v2/events lists every event the API serves under one sport key or prefix, the matched boards' and raw's alike, with what names it (teams, venue or event_name) and its competition_key. has_coverage lists the matched boards carrying each event, and is [] for an event only raw serves.

Any sport the API serves, greyhound_racing included, is a valid sport, and /v2/sports lists it. eventIds, at most 50 ids, looks up any id the API serves, and an id merged into another returns the event it became.

It costs no tokens but needs a key. It pages 250 events at a time, in order of kick-off, then id, and a cursor expires 300 s after it was issued: dedupe by id.

Look events up

# 1. Every greyhound race the API serves, free: has_coverage is [] for a race only raw serves
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events?region=uk&sport=greyhound_racing"

# 2. The ids you hold, comma-separated: an id merged into another returns the event it became
curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \
  "https://api.oddsrelay.io/v2/events?region=uk&sport=horse_racing&eventIds=$EVENT_IDS"

Every parameter: API reference.