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.
leagueis the track, with itscountry;namereads like "Belmont Park R5";startAtis the post time, and moves when the race is delayed;detailsis{raceNumber, distance, surface}. Racing events have norotationand noschedule. - Participants: the runners, with
role: runnerandnumber(saddle cloth or trap).detailsis{jockey, trainer, weightLb, medication, scratched, morningLine, morningLineFraction}.jockeyis the driver in harness racing andnullfor greyhounds;medicationis 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_doubleandpick_3topick_7, all with the periodraceand in the market groupracing. Each selection is a runner, with itsnumberinparticipant.legssays how many runners a bet names. - Multi-race pools (daily double, pick N) are on the event of their first race.
raceEventIdslists the races in order, and the selections are the runners of all of them, each with itsleg(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 on1wins when1Afinishes 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 participantdetailssayscratched: true, and the result lists it inscratched. - 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.baseis 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.paidincludes the stake. legsis the winning combination: one per position (single-race pools) or per race (multi-race pools), with the runners'numbersandparticipantIds. A leg with more than one number (a dead heat, a coupled entry) is won by any of them;anyRunner: truemeans 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
marketIdis the market you took the bet on, ornullwhen 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
basemultiplied by the dogs tied, so the same formula applies the dead-heat rule. note: "CARRYOVER"(withpaid: 0and no legs) means nobody won: those bets lose.
Refunds, held pools and no dividend¶
racing.refundslists 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.heldlists the pools the final result does not settle yet, each with itsmarketType, itsmarketId(nullwhen no such market was published), itsreasonanduntil(ISO 8601 in UTC). Settle or refund nothing on them: a later result (corrected: true) pays them or lists them inrefunds, byuntilat the latest. The one reason today isawaiting_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
resultmessage, for a race no longer on the board too: match it byeventId.
Racing is not graded¶
The Grading add-on does not cover racing: settle on the dividends of the final result.