Racecards are the front door
/v1/racecardsAll live plansPaginated races, each with nested runners, finishers and wagers where supplied.
Almost every integration starts here. A racecard item is a race: it carries id, name, date, time, distance, class, going, a course object with id and name, and a runners array. Each runner carries its horse id, name, number, jockey and trainer objects, supplied form rows, odds rows and usually a silkUrl. Those IDs are the keys you will pass to every other endpoint.
An empty data array is a valid answer on a day with no racing in the feed. It is not an error, and it is not a cancellation flag. A failed request always returns an error body with a non-2xx status, so never treat a failure as an empty schedule.
Choosing the day: default, tomorrow and date
| You send | Feed returned | Notes |
|---|---|---|
| nothing | Today, Europe/London calendar | meta.date is null. |
| tomorrow=true | Tomorrow, Europe/London calendar | Declarations depend on source availability. |
| date=YYYY-MM-DD | That London calendar day | Today's and tomorrow's dates select their live feeds. Dated race and result requests provide ten years of UK and Irish racing history. |
| date and tomorrow=true together | HTTP 422 | Pick one selector. tomorrow=false does not select tomorrow. |
Dates follow the London calendar, including the switch between GMT and BST. If your server runs in UTC, compute the London date explicitly rather than taking the UTC date, especially just after midnight. Source times such as race.time are passed through as supplied: do not append a time zone that the source did not give you.
Collecting every page
Top-level lists use page (default 1) and limit (1 to 100, default 50). meta.total is the count before slicing. Keep requesting until page * limit >= meta.total. Lists are live rather than frozen, so deduplicate by ID in case a race moves between pages. Only the top-level list is paginated: a race's nested runners are always complete, and limit never trims them.
- 1page=1, limit=100. Request the first page with your chosen day selector.
- 2Merge by race id. Add races to a map keyed by id so repeats are ignored.
- 3page * limit >= total?. If yes, you are done. If not, increment page and request again.
- 4Cache the whole day. Store the merged list under a key that includes the date.
async function getRacecards(day = {} /* { date } | { tomorrow: true } | {} */) {
if (day.date && day.tomorrow) throw new Error("Choose date OR tomorrow");
const races = new Map();
for (let page = 1; ; page++) {
if (page > 1) await new Promise(resolve => setTimeout(resolve, 550));
const url = new URL("/v1/racecards", "https://racingapi.net");
url.searchParams.set("region", "uk");
url.searchParams.set("limit", "100");
url.searchParams.set("page", String(page));
if (day.date) url.searchParams.set("date", day.date);
if (day.tomorrow) url.searchParams.set("tomorrow", "true");
const res = await fetch(url, { headers: { "X-API-Key": process.env.RACINGAPI_KEY } });
const body = await res.json();
if (!res.ok) throw new Error(body.code + " " + body.requestId);
for (const race of body.data) races.set(race.id, race);
if (page * body.meta.limit >= body.meta.total) break;
}
return [...races.values()];
}
const tomorrow = await getRacecards({ tomorrow: true });The pagination examples pause between pages so one loop stays below the smallest plan's per-second limit. Other jobs using your account share that limit too: use one account-wide queue and the bounded retry helper in Limits and errors in a production integration. A race or horse ID shown as RACE_ID or HORSE_ID is a placeholder: replace it with an ID you just discovered, not the placeholder text.
Turning races into meetings
Racecards return races, not meetings. To show a meeting index, group races by course.id. Sort validated HH:mm times numerically by hour and minute; do not assume an arbitrary source time string sorts correctly. Keep the course name from the first race in the group and display the supplied going description separately from forecast weather.
- Join runners to anything else by
runner.id, never by array position. - Treat
runner.numberas text: it can contain a non-runner code. - Use text rendering for every supplied string. Do not inject source strings as HTML.
- Cache today's merged list for a short period and tomorrow's for longer; see Saving requests.
Reference material
Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.