# 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](https://oddsrelay.io/docs/guides/walking-raw#following-changes) 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](https://oddsrelay.io/docs/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"
```

Source: https://oddsrelay.io/docs/guides/event-ids · the API contract: https://oddsrelay.io/openapi.json
