Skip to content
Tutorials/Performance and operationsIntermediate12 min read

Save requests with shared football API caches

Design server-side caching, request coalescing, prewarming and usage budgets so football pages load quickly without unnecessary API calls.

Flow / Many visitors, one refresh
  1. Step 1: Visitors

    Read your own delivery route

  2. Step 2: Shared cache

    Return saved data immediately

  3. Step 3: One refresh

    Coalesce concurrent misses

  4. Step 4: API

    Collect only what changed

Start with the real cost of your polling plan

The largest request savings usually come from architecture, not shorter JSON. A request every five seconds runs 17,280 times per day if left active for 24 hours. A request every minute runs 1,440 times per day. Multiply by competitions, endpoints and independent servers before choosing your polling schedule.

Included successful requests reset at midnight UTC and are shared across the account's keys. New paid GBP subscriptions have £0.002 overages per additional successful request; 10,000 additional requests cost £20. Failed and denied requests are not billed. Starter trial usage is hard-capped without overage billing. These rules make a shared collector much more predictable than browser-driven polling.

  • Use one collector for a shared scoreboard, not one per visitor.
  • Do not poll completed matches at live-match frequency.
  • Batch profile imports and reuse image files.
  • Read usage headers and your dashboard before increasing polling.

Choose cache keys that cannot mix records

A good cache key includes the endpoint, sorted parameters and account access scope. Include the actual day for relative offsets, season for historical tables, and market plus line for odds. A cache keyed only by match name can merge different fixtures; a shared cache without entitlement scope can leak data across customers.

Our endpoint TTL describes our server-side reuse interval. It does not make a successful customer request free, does not guarantee a new underlying record each interval, and should not be confused with your own retention policy.

Coalesce concurrent requests in one server process

Save this dependency-free example as scores-cache.mjs on a Node.js 20+ server with FOOTBALLAPI_KEY set. Import and call readScores() from your own server route. It provides a five-second process-local cache and coalesces concurrent misses; it does not implement stale-while-revalidate or automatically start a polling job.

This example is for one fixed FootballAPI.net account and no query filters. Restart it and clear cached data when changing its key or access scope. Multi-account services need separate scope-aware caches, and multiple server replicas need a shared cache or coordinated collector. Only the current day's successful snapshot is retained in memory.

javascript
let cached;
let pending;
export async function readScores() {
  const day = new Date().toISOString().slice(0, 10);
  if (cached?.day === day && cached.until > Date.now()) return cached.value;
  if (pending?.day === day) return pending.promise;
  const promise = (async () => {
    const apiKey = process.env.FOOTBALLAPI_KEY;
    if (!apiKey) throw new Error('Set FOOTBALLAPI_KEY');
    const response = await fetch('https://footballapi.net/api/v1/football/scores', {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(60000)
    });
    if (!response.ok) throw new Error(`Football HTTP ${response.status}`);
    const value = await response.json();
    // Do not let yesterday's slower request overwrite a new-day snapshot.
    if (new Date().toISOString().slice(0, 10) === day) {
      cached = { day, value, until: Date.now() + 5000 };
    }
    return value;
  })();
  pending = { day, promise };
  try { return await promise; }
  finally { if (pending?.promise === promise) pending = undefined; }
}

Prepare the page before the visitor opens it

Run fixture imports for the calendar dates your product exposes. Prepare saved match detail, portraits and available quotes in the background. The match tabs should read one combined saved model; switching from summary to lineups is not a reason to start an unrelated full import.

For stale-while-revalidate delivery, return a known saved response promptly while one job refreshes it. Keep the original fetched time. Do not silently describe an old snapshot as live, and do not replace a successful saved record with a timeout or an empty transport failure.

Use different refresh rules for different data

Competition directories and identity metadata change slowly. Future fixtures need periodic reconciliation. Active matches need short shared updates, while finished matches can move to a correction schedule. Stored crests and portraits should be served as image assets rather than repeatedly fetched as base64 JSON.

Introduce job concurrency limits, jitter and a bounded retry budget. When requests are rate-limited, respect Retry-After and spread later work instead of waking every queue worker at exactly the same second. Monitor total requests and useful record changes together; high request volume with no useful updates is a signal to adjust the collector.

All 51 tutorials