Skip to content

TutorialsLesson 6 of 15Racing data8 min read

Horse form statistics: summary rows by section

Render supplied horse form statistics from /v1/horses/{id}/form: race record, conditions, headgear, class rating and connections, grouped by section.

  • Request form for the right declaration
  • Group and render every supplied section
  • Explain clearly what the numbers do not mean

What the form endpoint returns

GET/v1/horses/{id}/formAll live plans

Supplied summary statistics for a declared horse, grouped by section.

The response data contains horseId, horseName, raceId, raceName, course, feedDate, declarations[], scope and form[]. Each form row has section, name, runs, wins, places and winPercentage, all as strings. Sections can include race record, conditions, headgear, class rating and connections when supplied. Availability varies by horse.

These are aggregate summary rows. Individual prior-run records are available separately through dated race and result endpoints across ten years of UK and Irish racing history. The summary response here is not the limit of the API's historical coverage. A last-four-runs strip appears in the RacingAPI.net widgets, but that compact form line is a widget display feature, not something this endpoint returns.

For race-by-race research, list GET /v1/results?region=uk&date=YYYY-MM-DD, follow pagination, and match each finisher's horseId to the horse you are researching. Retrieve /v1/results/{raceId} and /v1/races/{id} with the same date for the individual result and race details. Repeat for the dates you need and cache dated records on your server so other horse investigations can reuse them. See Results and dividends. Historical requests use the same API key and plan allowance as current-day requests.

Request and group

async function horseForm(horseId, raceId, date) {
  const url = new URL("/v1/horses/" + encodeURIComponent(horseId) + "/form", "https://racingapi.net");
  url.searchParams.set("region", "uk");
  url.searchParams.set("raceId", raceId);
  if (date) url.searchParams.set("date", date);
  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);

  // Group by section, keeping unknown future section names too
  const sections = new Map();
  for (const row of body.data.form) {
    if (!sections.has(row.section)) sections.set(row.section, []);
    sections.get(row.section).push(row);
  }
  return { horse: body.data.horseName, sections };
}

Display rules that keep you honest

  • Render every supplied section, including section names you have not seen before.
  • Show winPercentage as the supplied string. Do not recompute it or present it as a probability.
  • places uses the source's own definition of a place; label it 'places' rather than 'top three'.
  • Empty strings mean not supplied. Show a dash, not zero.
  • Do not sum connection rows across horses to manufacture jockey or trainer career statistics.

Current-day statistics are prepared from 06:30 London time and saved in a shared cache for 24 hours, so a matching horse, race and date can be served without waiting on a new feed download. Your own cache can therefore hold form for the whole day: form rows do not change minute to minute the way prices do. Read the field list in the API reference.

Reference material

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