Skip to content

TutorialsLesson 8 of 15Media and prices10 min read

Racecourses and course weather forecasts

List courses in a UK and Irish daily feed, open one course with its races, and show attributed course-location weather forecasts from /v1/racecourses/{id}/weather.

  • List the day's courses and going
  • Open one course and its races
  • Display forecasts with the required attribution

Courses racing in a feed

GET/v1/racecoursesAll live plans

Courses appearing in the selected daily feed, with id, name and going.

This is a list of courses with races in the chosen feed, not a permanent course directory. Each item has id, name and going. It is the lightest way to build a 'meetings today' strip when you do not need runners yet. It is paginated like every other list.

const url = new URL("/v1/racecourses", "https://racingapi.net");
url.searchParams.set("region", "uk");
if (process.env.RACE_DATE) url.searchParams.set("date", process.env.RACE_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);
const meetings = body.data.map(c => ({ id: c.id, name: c.name, going: c.going || "Going not supplied" }));

One course and its races

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

A course from the selected feed with its races[].

Replace {id} with race.course.id or an ID from the course list. These examples use today unless RACE_DATE is set to YYYY-MM-DD; carry that same date through list, detail and weather lookups. A course may race tomorrow but not today. The detail object adds races for that course in the selected feed. If you already hold all racecards for the day, group them by course instead of making another request.

import os, requests

res = requests.get(f"https://racingapi.net/v1/racecourses/{os.environ['COURSE_ID']}",
                   params={"region": "uk", **({"date": os.environ["RACE_DATE"]} if os.environ.get("RACE_DATE") else {})},
                   headers={"X-API-Key": os.environ["RACINGAPI_KEY"]}, timeout=15)
res.raise_for_status()
course = res.json()["data"]
print(course["name"], course["going"])
for race in course["races"]:
    print(" ", race["time"], race["name"])

Course-location weather forecasts

GET/v1/racecourses/{id}/weatherAll live REST plans

Latest forecast for the course location, with temperature, rainfall, wind and humidity.

Weather uses the same key, rate limit and monthly allowance as other feeds. date or tomorrow=true only help find the course in the racing feed; they do not request historical weather. The response always holds the latest available forecast, up to roughly nine days ahead depending on source coverage. Weather is a REST feature and is not shown in the website widgets.

data contains course (id, name, latitude, longitude), type of forecast, timezone of UTC and an unpaginated, chronological forecast[]. Each point has time, temperatureC, humidityPercent, windSpeedMps, windFromDegrees, symbolCode, precipitationMm and precipitationPeriodHours. Null means not supplied, never zero.

async function courseWeather(courseId, date) {
  const url = new URL("/v1/racecourses/" + encodeURIComponent(courseId) + "/weather", "https://racingapi.net");
  url.searchParams.set("region", "uk");
  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);     // e.g. weather_unavailable
  const { meta, data } = body;
  return {
    course: data.course.name,
    expiresAt: meta.expiresAt,                 // cache until this instant
    credit: meta.source.attribution,
    sourceUrl: meta.source.url,
    licenceUrl: meta.source.licenceUrl,
    points: data.forecast.map(p => ({
      at: new Date(p.time).toLocaleString("en-GB", { timeZone: "Europe/London" }),
      tempC: p.temperatureC,
      windMph: p.windSpeedMps == null ? null : Math.round(p.windSpeedMps * 2.23694),
      rainMm: p.precipitationMm,
      rainHours: p.precipitationPeriodHours,
    })),
  };
}
  • Cache each course forecast until meta.expiresAt; weather has its own expiry, separate from racing snapshots.
  • Convert UTC time to Europe/London or Europe/Dublin for display, allowing for daylight saving.
  • precipitationMm covers the period after time lasting precipitationPeriodHours. Do not add overlapping periods.
  • Forecast weather is not official going. Keep going from the racecard next to it, clearly labelled.
  • Errors are explicit: 404 when the course is absent from the feed, 422 weather_location_unmapped, 503 weather_unavailable or weather_format_error.

Full field notes are in the API reference.

Reference material

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