Skip to content

TutorialsLesson 15 of 15Operations11 min read

Saving requests: shared caches, deduplication and budgets

Make RacingAPI.net allowance last: understand the shared server cache, cache by date, deduplicate in-flight requests, poll only active races and estimate budgets.

  • Match your cache to the server snapshot windows
  • Collapse duplicate requests in flight
  • Estimate a daily budget with stated assumptions

What the server already caches

RacingAPI.net reuses shared daily-feed snapshots within short cache windows. Meta.cached tells you a snapshot was reused, and cached requests still count towards allowance. Fetching faster normally repeats the same snapshot; it does not force the source or bookmakers to publish updates. Cache windows are ceilings, not guaranteed refresh intervals.

DataShared cache
Current-day racecards, odds and results listUp to 5 seconds
Tomorrow's feedUp to 5 minutes, refreshed ahead in the background
Archive datesUp to 30 seconds
Published individual resultUp to 5 minutes
Historical results lists observed after 06:00 London on a later dayUp to 6 hours
Generated silk PNGsUp to 24 hours
Horse form statisticsPrepared from 06:30 London, saved 24 hours
Course weatherUntil meta.expiresAt
Server snapshot windows (ceilings, not update guarantees)

Your cache: keyed by endpoint, params and date

Put one cache in front of every RacingAPI.net call on your server. The cache key must include the path, every query parameter and the resolved London date, so today's racecards never answer a request for tomorrow and a cached 'today' expires naturally at midnight. Choose expiry by how fast the data really moves: seconds for odds, minutes for racecards and results, the whole day for form, and the full life of silks.

DiagramCache with in-flight deduplication
Cache with in-flight deduplication: step 1, Request arrives; step 2, Fresh entry?; step 3, Already in flight?; step 4, Fetch once.1 VISITORRequest arrives2 CACHEFresh entry?3 YOUR SERVERAlready in flight?4 RACINGAPI.NETFetch once
  1. 1Request arrives. Build a key from path, params and London date.
  2. 2Fresh entry?. Serve it immediately. Zero upstream requests.
  3. 3Already in flight?. Await the same promise instead of starting another call.
  4. 4Fetch once. One request to /v1; store the result; resolve all waiters.
Ten simultaneous visitors on a cold cache still produce one upstream request.
const store = new Map();     // key -> { body, expires }
const inflight = new Map();  // key -> Promise

function londonDate(offsetDays = 0) {
  const today = new Date().toLocaleDateString("en-CA", { timeZone: "Europe/London" });
  const calendar = new Date(today + "T12:00:00Z");
  calendar.setUTCDate(calendar.getUTCDate() + offsetDays);
  return calendar.toISOString().slice(0, 10); // Calendar days, not 24-hour offsets across DST
}

export async function cached(path, params = {}, ttlMs = 5000) {
  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new Error("Use a positive cache lifetime");
  const tomorrow = params.tomorrow === true || params.tomorrow === "true";
  if (params.date && tomorrow) throw new Error("Choose date OR tomorrow");
  const day = params.date || (tomorrow ? londonDate(1) : londonDate());
  const resolved = { ...params, date: day };
  delete resolved.tomorrow; // Pin the request itself to the date used by the key.
  const key = path + "?" + new URLSearchParams(Object.entries(resolved).sort()).toString();
  const hit = store.get(key);
  if (hit && hit.expires > Date.now()) return hit.body;
  if (inflight.has(key)) return inflight.get(key);

  const p = racingGet(path, resolved)        // the retry helper from the limits lesson
    .then(body => {
      if (store.size >= 500) store.delete(store.keys().next().value);
      store.set(key, { body, expires: Date.now() + ttlMs });
      return body;
    })
    .catch(err => {
      const transient = [500, 502, 503, 504].includes(err.status);
      if (transient && hit && Date.now() - hit.expires < 300_000) return hit.body;
      throw err; // Never hide invalid credentials, lost access, or old data indefinitely
    })
    .finally(() => inflight.delete(key));
  inflight.set(key, p);
  return p;
}

// Usage
const cards = await cached("/v1/racecards", { limit: 100 }, 60_000);
const prices = await cached("/v1/odds/" + raceId, {}, 5_000);

Habits that save the most

  • Use nested runners from racecards instead of per-runner calls (Race details).
  • Fetch lists with limit=100 to minimise page requests.
  • Poll odds only for races that are imminent and visible, and stop at the off (Live odds).
  • Poll results slowly after the off and stop once a race has finishers.
  • Search horses in your cached racecards before calling search.
  • Never use feed endpoints as health probes; HEAD requests count too.
  • Run one shared poller per resource for the whole server, not one per visitor or worker.

Estimating a monthly budget

JobAssumptionRequests per day
Racecards refreshEvery 2 minutes for 10 hours, 1 page300
Tomorrow's cardEvery 30 minutes for 12 hours24
Results listEvery 2 minutes for 7 hours210
Odds for imminent races5 s polling, 10 minutes before each off3,600
SilksOne per runner, cached for the day, 300 runners300
Daily total4,434
Assumed: 30 race days a month, 30 races a day, one shared server cache

Under those assumptions a month of 30 race days is roughly 133,000 requests, which exceeds a 100,000 allowance. Halving the odds window, or polling odds every 10 seconds, brings it under. Without a shared cache, the same site would multiply each line by its concurrent visitors. This is why caching, not raw polling speed, decides which plan you need.

See Limits and errors for the retry helper used above, and the documentation for full caching semantics.

Reference material

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