Skip to content

Horse racing

Product id: racing

Horse, harness and greyhound racing (sports horse_racing, harness_racing and greyhound_racing): race cards, pari-mutuel pools and official results with their dividends.

Racing is pari-mutuel: a winning bet is paid what its pool pays, known only once the race is official. There are no fixed odds, so every selection's price is null.

Only what can be settled is offered. A track's races are published only while its official results reach us: a track with no official result in the 7 days before a meeting is left out (no events, no markets) until one arrives. Once a meeting is offered it stays offered: a race is never withdrawn before it runs. Every race you can bet here has a result coming.

Races, runners and pools

  • Event: one per race. league is the track, with its country; name reads like "Belmont Park R5"; startAt is the post time, and moves when the race is delayed; details is {raceNumber, distance, surface}. Racing events have no rotation and no schedule.
  • Participants: the runners, with role: runner and number (saddle cloth or trap). details is {jockey, trainer, weightLb, medication, scratched, morningLine, morningLineFraction}. jockey is the driver in harness racing and null for greyhounds; medication is as the program prints it.
  • The morning line is not a price. It is the track's forecast of the odds, printed before betting opens, and the only odds figure a race card has. Show it as a guide; never take a bet at it.
  • A runner's par_ id names it in one race. Do not join races on it.
  • Markets: one per pool, by type: win, place, show, exacta, quinella, trifecta, superfecta, forecast, tricast, daily_double and pick_3 to pick_7, all with the period race and in the market group racing. Each selection is a runner, with its number in participant. legs says how many runners a bet names.
  • Multi-race pools (daily double, pick N) are on the event of their first race. raceEventIds lists the races in order, and the selections are the runners of all of them, each with its leg (1 for the first race). A bet names one runner per leg.
Form Types A bet names
runner win, place, show One runner
ordered exacta, trifecta, superfecta, forecast, tricast legs runners, in finishing order
unordered quinella legs runners, in any order
multi_race daily_double, pick_3 to pick_7 One runner in each race of raceEventIds

Coupled entries and scratches

These follow the usual North American pari-mutuel rules.

  • Coupled entries. Runners of one race whose selections share a couplingGroup (1, 1A, 1X) are one betting interest. A bet on any of them is a bet on the entry; a dividend that names any member pays every bet on the entry (a bet on 1 wins when 1A finishes first); if a member is scratched and another still runs, the entry runs and its bets stand.
  • Scratches. A scratched runner's selection is closed, its participant details say scratched: true, and the result lists it in scratched.
  • Win, place and show: a bet on a scratched runner (on the whole entry, if coupled) is refunded.
  • Exacta, quinella, trifecta, superfecta, forecast and tricast: a combination with a scratched runner is refunded.
  • Daily double and pick N: a scratch in the first race refunds the bet. A scratch in a later race is settled by the track's own rule for that pool: most tracks give the bet the post-time favourite, some pay a consolation. Set your rule in your terms.

When betting stops

Status When
market open Betting is open
market suspended 90 s before post, or the track stopped taking bets on the pool. It reopens if the post moves later
market closed Betting closed for good: the race is off
selection closed The runner was scratched. It does not come back
event live The race is off, or run and not yet official
event finished The result is official (racing.final: true)
event cancelled The race was not run: every bet on its single-race pools is refunded. A multi-race pool that starts in it or runs through it is still settled by the dividends of its last race, where that leg counts as anyRunner

Results and dividends

A race's result comes as a result message, and at GET /v1/racing/results/{eventId}; every result since a time is at GET /v1/racing/results?updatedSince=…. It can come several times: each one replaces the last. GET /v1/events/{eventId} links it under result.

Field of racing What it is
final Settle only on true. false is provisional: show it, never settle on it
corrected These numbers replace ones already published as final (an inquiry, a disqualification): check anything you settled on the old ones
offAt When the race actually started: void any bet accepted after it
currency ISO 4217 code of the dividends, when the track states it
finishers Positions 1 to 3 (4 where a place pays four), with number, participantId and name
dividends Every winning combination of every pool that ends in this race
refunds The pools whose every bet is returned
held The pools not settled yet: {marketType, marketId, reason, until}
scratched The runners withdrawn

A result also carries its event's sport and league (the track), because it outlives the event.

Paying a dividend

  • Pay stake / base × paid. base is the stake the dividend is quoted for, and it changes by pool and by country (2.00 for win, place and show in North America; 1.00, 0.50, 0.20 or 0.10 for exotics): never assume it. paid includes the stake.
  • legs is the winning combination: one per position (single-race pools) or per race (multi-race pools), with the runners' numbers and participantIds. A leg with more than one number (a dead heat, a coupled entry) is won by any of them; anyRunner: true means every runner counts in that leg.
  • Multi-race pools end in their last race: a pick 4 over races 5 to 8 is paid in the result of race 8. A dividend's marketId is the market you took the bet on, or null when no such market was published.
  • A pool can pay several dividends: dead heats, and consolations (note: "5 OF 6").
  • Dead heats come already split in the dividends of tote pools, North American greyhounds included: pay each one as it is. A greyhound dead heat for first settled at the starting price (Great Britain, Ireland, Australia) comes with each dog's whole price and base multiplied by the dogs tied, so the same formula applies the dead-heat rule.
  • note: "CARRYOVER" (with paid: 0 and no legs) means nobody won: those bets lose.

Refunds, held pools and no dividend

  • racing.refunds lists the pools whose bets all get their stake back: the pools the track refunded, and a place or show pool the track ran without a dividend for anybody (a small field sells no show).
  • racing.held lists the pools the final result does not settle yet, each with its marketType, its marketId (null when no such market was published), its reason and until (ISO 8601 in UTC). Settle or refund nothing on them: a later result (corrected: true) pays them or lists them in refunds, by until at the latest. The one reason today is awaiting_official_dividend: a pick 5 or pick 6 taken from the track's published program, whose dividend or carryover can come up to 3 hours after the race's result.
  • No dividend, no payout: a bet on a pool that is neither paid, refunded nor held in the final result has no official dividend. Refund it.

How long things stay

  • A race leaves the board (event.remove) 2 hours after its result became final, or 24 hours after its post if no final result comes.
  • Its result stays 7 days after it was published, also once the event is gone. A correction in that time still comes as a result message, for a race no longer on the board too: match it by eventId.

Racing is not graded

The Grading add-on does not cover racing: settle on the dividends of the final result.