Skip to content

TutorialsLesson 3 of 15Foundations8 min read

Race details without N+1 calls

Fetch a single UK or Irish race with /v1/races/{id}, understand nested runners, prices and results, and avoid the N+1 request pattern that wastes allowance.

  • Fetch one race by ID in the right feed
  • Use nested runners instead of per-horse calls
  • Know when a detail call is worth it

One race, everything nested

GET/v1/races/{id}All live plans

A race, its declared runners, available bookmaker prices and any published finishers and wagers.

Replace {id} with a race.id copied from /v1/racecards for the same day. The response data is one race object with the same shape as a racecard item: runners[] with jockey, trainer, form rows and odds rows, plus finishers[] and wagers[] once a result is supplied. A race ID that does not exist in the selected feed returns 404 with code resource_not_found.

curl --fail-with-body \
  "https://racingapi.net/v1/races/$RACE_ID?region=uk&date=$RACE_DATE" \
  -H "X-API-Key: $RACINGAPI_KEY"

The N+1 trap and how nested runners avoid it

N+1 is the habit of fetching a list and then making one extra request for every item in it. On a busy Saturday a single card can hold well over a hundred runners. Calling /v1/horses/{id} for each runner to get its jockey, trainer, weight and prices would spend hundreds of requests to learn what the racecard already told you in one.

DiagramN+1 versus nested data
N+1 versus nested data: step 1, Racecards page; step 2, Render the card; step 3, Avoid: per-runner loop; step 4, Only on demand.1 RACINGAPI.NETRacecards page2 YOUR SERVERRender the card3 STOPAvoid: per-runner loop4 CACHEOnly on demand
  1. 1Racecards page. 1 request returns up to 100 races with every runner nested.
  2. 2Render the card. Jockey, trainer, weight, rating, stall and prices come from the nested runner.
  3. 3Avoid: per-runner loop. Requesting each horse separately repeats data you already hold.
  4. 4Only on demand. Call detail endpoints when a visitor opens one race or one horse.
One list request already contains runners, connections, form rows and prices.

So when is /v1/races/{id} worth calling? When a visitor deep-links straight to one race and you have no cached card for that day, when you want a single race refreshed after the off without re-downloading every page, or when a background job checks one specific race for finishers. If you already hold today's racecards in cache, read the race from there.

Rendering a race safely

  • Show offAt only when it is non-empty; it is the source's actual-off string.
  • Show going, distance and class as supplied strings, without unit conversion.
  • Racecards and /v1/odds/{raceId} use the same shared daily snapshot. The odds endpoint is a smaller price-focused response, not a separate faster feed; see Live odds.
  • When finishers is non-empty, switch the view to a result; Results and dividends covers that shape.
  • Fetch silk images through your own server route using each runner's silkUrl; see Racing silks.

Full field definitions for races and runners are in the API reference.

Reference material

Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.