Skip to content

TutorialsLesson 9 of 15Media and prices8 min read

Racing silks: binary PNG images through your own route

Download racing-colour PNGs from /v1/silks/{id} with the required raceId, proxy them through your server without exposing your key, and cache them properly.

  • Request a silk with the required raceId
  • Handle binary bodies and JSON errors
  • Serve silks to browsers without leaking your key

A binary endpoint with JSON errors

GET/v1/silks/{id}Included with active API access

A generated RacingAPI.net racing-colour PNG for one horse in one race.

{id} is the horse ID (1 to 12 digits). raceId is required and must be the race that horse is declared in, from the same region and day. Add date or tomorrow=true when you are not on today's feed. Each runner and finisher also carries a ready-made silkUrl: a relative, authenticated path for exactly this horse, race and date, which you can append to the base URL on your server.

Success is image/png bytes. Failure is the standard JSON error body. A runner with no generated silk ready returns 404 silk_not_found; we never substitute an invented image, so show a neutral placeholder. Silks are racing colours, not portraits, and need no separate approval.

Proxy pattern: your route, your cache

DiagramServing silks to visitors
Serving silks to visitors: step 1, <img src=/silks/HORSE?race=RACE>; step 2, Your image route; step 3, /v1/silks/{id}?raceId=; step 4, Cache and stream.1 VISITOR<img src=/silks/HORSE?race=RACE>2 YOUR SERVERYour image route3 RACINGAPI.NET/v1/silks/{id}?raceId=4 CACHECache and stream
  1. 1<img src=/silks/HORSE?race=RACE>. The page points at your own route. No key in the URL.
  2. 2Your image route. Validates both IDs as digits, then checks a disk or memory cache.
  3. 3/v1/silks/{id}?raceId=. Called on a cache miss with X-API-Key.
  4. 4Cache and stream. Store the PNG and send it with a long Cache-Control.
Browsers request your image route. Only your server holds the key.
// Express-style handler: GET /silks/:horseId?race=RACE_ID&date=YYYY-MM-DD
const cache = new Map(); // swap for disk or object storage in production

export async function silkRoute(req, res) {
  const horseId = String(req.params.horseId);
  const raceId = String(req.query.race || "");
  const date = req.query.date ? String(req.query.date)
    : new Date().toLocaleDateString("en-CA", { timeZone: "Europe/London" });
  if (!/^\d{1,12}$/.test(horseId) || !/^\d{1,12}$/.test(raceId)) return res.status(400).end();
  if (date && !/^\d{4}-\d{2}-\d{2}$/.test(date)) return res.status(400).end();

  const key = horseId + ":" + raceId + ":" + date;
  const saved = cache.get(key);
  let png = saved && saved.expires > Date.now() ? saved.png : null;
  if (!png) {
    const url = new URL("/v1/silks/" + horseId, "https://racingapi.net");
    url.searchParams.set("region", "uk");
    url.searchParams.set("raceId", raceId);
    if (date) url.searchParams.set("date", date);
    const upstream = await fetch(url, { headers: { "X-API-Key": process.env.RACINGAPI_KEY } });
    if (upstream.status === 404) return res.status(404).end();   // show your placeholder
    if (!upstream.ok) return res.status(502).end();
    png = Buffer.from(await upstream.arrayBuffer());
    if (cache.size >= 2000) cache.delete(cache.keys().next().value);
    cache.set(key, { png, expires: Date.now() + 86_400_000 });
  }
  res.set("Content-Type", "image/png");
  res.set("Cache-Control", "public, max-age=86400");
  res.send(png);
}

Caching and fair use

  • Silk requests count like any other request. Caching on your side is what keeps a 400-runner card affordable.
  • Successful PNGs can be reused from the gateway cache for up to 24 hours. Repeated requests consume allowance and do not force image regeneration.
  • Never build an image URL that includes your key. Never hand silkUrl straight to a browser; it needs authentication.
  • Silks support your own racing displays. Do not publish them as a standalone image library.

See the API reference for the silk error codes.

Reference material

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