mapshttpcache-control

Implementing Stale-While-Revalidate for Map Tiles: Improving Perceived Performance without Stale Data Surprises

UUnknown

2026-02-12

10 min read

Concrete SWR configs for map tiles and POI overlays: headers, server and service-worker examples, revalidation guidance, and staleness metrics.

Hook — Your map loads fast, but are you serving stale POIs?

Slow tile and POI loads kill perceived performance; aggressive caching reduces origin costs but risks serving out-of-date points-of-interest (POI) that confuse users and break business rules. In 2026, with real-time overlays and edge compute everywhere, stale-while-revalidate (SWR) is the pragmatic sweet spot: it preserves instant perceived performance while revalidating in the background. This guide gives concrete Cache-Control headers, server configs, service-worker examples, revalidation frequency rules, and metrics you can instrument today.

Top-line recommendations (inverted pyramid)

Base map tiles: long max-age + long SWR (keep tiles instant and cheap to serve).
POI overlays: short max-age + short SWR (freshness matters; keep perceived latency low).
Edge behavior: implement background revalidation at the edge (Nginx proxy_cache_background_update, Varnish background fetch, or Cloudflare Worker).
Client fallback: return cached tile immediately, start a background fetch, and gracefully swap updated tiles when available (Service Worker pattern).
Metrics: track stale_served_ratio, revalidation_latency, cache_hit_ratio_by_layer, and tile_age distribution; create alerts when staleness SLOs are violated.

Why SWR matters for map tiles in 2026

Two trends that matter in 2026: broad HTTP/3 adoption reduced RTTs for tile fetches, and edge compute makes background revalidation cheap and distributed. At the same time, modern applications overlay volatile datasets (traffic, crowdsourced POIs, availability flags) on stable base tiles. Using stale-while-revalidate lets you:

Keep perceived latency near zero: return cached tiles instantly.
Maintain eventual freshness: trigger revalidation and replace stale tiles once the origin responds.
Lower origin load/costs: background revalidation consolidates origin requests and prevents thundering herds.

RFC 5861 codified stale-while-revalidate behavior; modern CDNs and reverse proxies now expose patterns and headers that make it safe for map stacks.

Key risks: the “stale data surprise”

Serving stale POI data without clear bounds can break user trust (e.g., a closed restaurant shown as open). Mitigate surprises by:

Classifying data layers by volatility (static tiles vs highly dynamic POIs).
Setting conservative SWR windows for critical overlays.
Using versioned tile keys or targeted purge APIs for urgent corrections.
Exposing tile age to clients (Age or X-Cache-Age) and surfacing a small UI hint for highly dynamic layers.

Layered SWR strategy: base tiles, POI overlays, vector tiles

Design separate caching policies per logical layer. Examples below assume a CDN/edge in front of your tile origin.

1) Base raster tiles (z/x/y.@2x.png)

Characteristics: low volatility, large bandwidth footprint.

Cache-Control: public, max-age=86400, stale-while-revalidate=604800

Rationale: one day TTL and up to 7 days stale while the edge refreshes in background. Use when base tiles rarely change (style or imagery updates are infrequent).

2) Vector base tiles (MVT)

Cache-Control: public, max-age=86400, stale-while-revalidate=86400

Treat similarly to raster tiles; vector tiles are smaller. If you do on-the-fly rendering at the edge, you may reduce max-age to 3600 and rely on edge compute to re-bake tiles quickly.

3) POI overlays (restaurants, availability flags)

Characteristics: high volatility, small payloads per tile but high business impact.

Cache-Control: public, max-age=60, stale-while-revalidate=30, stale-if-error=86400

Rationale: a 60s TTL keeps origin updates timely, but SWR 30s means the user usually sees cached overlay instantly while the edge revalidates. stale-if-error gives resilience during origin outages.

4) Real-time event overlays (incident alerts)

For emergency events, avoid long SWR windows; prefer versioned keys or targeted purge APIs. Example:

Cache-Control: public, max-age=10, stale-while-revalidate=5

Concrete server-side examples

Below are runnable examples that implement SWR behavior on common components in a map stack.

Nginx (reverse proxy with background updates)

Use proxy_cache_background_update and proxy_cache_use_stale. This serves cached content immediately and triggers an asynchronous update when the cached copy is stale.

http {
  proxy_cache_path /var/cache/nginx/tiles keys_zone=tiles:100m inactive=7d max_size=10g;

  server {
    location /tiles/ {
      proxy_cache tiles;
      proxy_cache_valid 200 302 1d;  # default TTL if origin doesn't set Cache-Control
      proxy_cache_valid 404 1m;

      # Allow serving stale while revalidating
      proxy_cache_use_stale updating error timeout invalid_header http_500 http_502 http_503 http_504;
      proxy_cache_background_update on;

      proxy_pass http://tile-origin;
    }
  }
}

Notes: rely on origin Cache-Control when present; use proxy_cache_background_update to avoid blocking requests.

Varnish (VCL) — stale-while-revalidate pattern

Varnish doesn't read SWR headers automatically; implement a background fetch when object is expired. Example VCL snippet:

sub vcl_hit {
  if (obj.ttl >= 0s) {
    return (deliver);
  }
  # Object expired: deliver stale copy and start background fetch
  if (obj.ttl < 0s) {
    stash(req.http.X-Background-Fetch, "1");
    return (deliver);
  }
}

sub vcl_backend_response {
  set beresp.ttl = 60s; # POI example
  set beresp.grace = 30s; # serve stale during grace and background fetch
}

sub vcl_deliver {
  if (obj.grace > 0s) {
    set resp.http.X-Cache-Status = "HIT; stale-grace";
  }
}

Notes: Varnish’s grace window is your SWR window. Background fetches can be tuned with thread pool sizes.

Cloudflare Worker — explicit SWR behavior

Workers let you implement SWR semantics even if edge config is limited. This snippet returns cached value immediately and revalidates in the background.

addEventListener('fetch', event => {
  event.respondWith(handle(event.request));
});

async function handle(request) {
  const cache = caches.default;
  const cacheKey = new Request(request.url, request);

  // Try cached response
  let cached = await cache.match(cacheKey);
  if (cached) {
    // Kick off background refresh
    event.waitUntil(revalidate(cacheKey, request));
    return cached;
  }

  // No cached value: fetch and cache
  let res = await fetch(request);
  event.waitUntil(cache.put(cacheKey, res.clone()));
  return res;
}

async function revalidate(cacheKey, request) {
  const cache = caches.default;
  try {
    const res = await fetch(request, { cf: { cacheTtl: 60 } });
    if (res.ok) await cache.put(cacheKey, res.clone());
  } catch (err) {
    // Keep stale; optionally increment a metric
  }
}

Client-side: Service Worker SWR pattern for tiles

On the browser, a Service Worker can implement SWR: match cache, return immediately, fetch in background and update cache so the next navigation gets fresh tiles.

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  if (url.pathname.startsWith('/tiles/')) {
    event.respondWith((async () => {
      const cache = await caches.open('tiles-v1');
      const cached = await cache.match(event.request);
      if (cached) {
        // Return cached instantly
        event.waitUntil((async () => {
          try {
            const fresh = await fetch(event.request);
            if (fresh && fresh.ok) await cache.put(event.request, fresh.clone());
          } catch (e) { /* network error: keep stale */ }
        })());
        return cached;
      }
      // Not cached: fetch, cache, return
      const response = await fetch(event.request);
      if (response && response.ok) await cache.put(event.request, response.clone());
      return response;
    })());
  }
});

Fallback UX patterns:

Show a low-resolution placeholder tile immediately, swap in cached tile when available.
For POIs, show last-known status and a small badge indicating “may be out-of-date” when age > threshold.

Revalidation frequency — concrete guidance

Choose max-age and SWR based on layer volatility and user expectations. The numbers below are starting points; tune with real metrics.

Static base imagery: max-age=86400 (1 day), SWR=604800 (7 days).
Base vector tiles: max-age=86400, SWR=86400.
POI: low volatility (business hours): max-age=300s (5m), SWR=60s.
POI: high volatility (availability, delivery status): max-age=60s, SWR=30s.
Critical alerts: max-age=10s, SWR=5s and use purge when necessary.

Principle: SWR window should be short relative to max-age for dynamic layers to limit the period a stale response is visible before an edge completes a background refresh.

Cache invalidation and urgent updates

For critical changes (safety updates, fraud remediation), rely on:

Versioned tile keys (append ?v=20260115): easy and reliable.
Targeted purge APIs from your CDN (Cloudflare, Fastly, AWS CloudFront) — automate via CI/CD.
Edge notifications (pub/sub) to trigger revalidation across POPs.

Metrics to track staleness — what to collect and PromQL examples

Instrument your edge and client with these metrics (labels: layer, zoom, region):

tile_cache_hits_total, tile_cache_misses_total
tile_background_revalidations_total
tile_stale_served_total (count of responses served from stale cache)
tile_revalidation_latency_seconds (histogram)
tile_age_seconds (histogram or summary)
tile_origin_errors_total (5xx, timeouts)

PromQL examples

Stale served ratio (last 5m):

sum(rate(tile_stale_served_total[5m]))
/ sum(rate(tile_cache_hits_total[5m]) + rate(tile_cache_misses_total[5m]))

Percentile of tile age for POI layer (p95 last 1h):

histogram_quantile(0.95, sum(rate(tile_age_seconds_bucket{layer="poi"}[1h])) by (le))

Alert rule example: trigger if stale_served_ratio > 0.05 for more than 10m for POI layer:

expr: (sum(rate(tile_stale_served_total{layer="poi"}[10m]))
/ sum(rate(tile_cache_hits_total{layer="poi"}[10m]) + rate(tile_cache_misses_total{layer="poi"}[10m]))) > 0.05
for: 10m

Observability: headers and RUM

Expose debugging headers to measure true client experience:

Cache-Status — parse CDN edge (e.g., "HIT", "MISS", "STALE").
Age — number of seconds since origin response.
X-Tile-Version — tile payload version to help correlate rollouts.

Collect RUM beacons that include tile age and cache-status for tiles used during page load, then join RUM data to backend metrics to track perceived performance and staleness impact on Core Web Vitals (LCP especially if a large tile is on-screen at load).

Benchmarks and testing

Test SWR behavior before rollout:

Simulate cache warm path and cold path using k6 or wrk; measure 95th percentile tile fetch latency.
Simulate origin slowdowns to verify stale responses served (and background revalidation behavior).
Run A/B comparing no-SWR vs SWR for POI overlay: measure LCP and overall origin egress costs.

Example expectations (real-world numbers will vary):

SWR should reduce median tile latency to ~network RTT (no origin hop) for cached items.
SWR should reduce origin request rate for base tiles by 90%+ after cache warmup.

Operational playbook for incidents

Detect: Alert on spike in tile_origin_errors_total or p95 revalidation_latency.
Mitigate: If POIs are wrong, issue targeted purge for affected keys or bump tile version to force refresh.
Communicate: Surface a small in-app status flag for “data may be stale”.
Post-mortem: Evaluate stale_served_ratio and whether SWR windows need tightening for the layer.

2026 trends and how they change the game

Key 2026 developments that inform strategy:

Wider HTTP/3 and QUIC adoption reduces penalty for origin fetches, but SWR still wins for first-paint-sensitive map experiences.
CDNs ship richer cache telemetry (Cache-Status, x-cache-hits) and background revalidation primitives — use them to simplify logic at the edge.
Edge compute (Workers, Edge Functions) makes custom SWR logic possible per-POP — helpful for geo-sensitive POIs.
Clients increasingly run Service Workers and use RUM; instrument tile age in beacons to tie perceived performance to cache behaviors.

Checklist: rollout SWR for your map stack

Classify layers: base, vector, POI, alerts.
Define TTL and SWR windows per layer — start conservative for POI.
Implement edge background revalidation (Nginx/Varnish/Worker or CDN feature).
Add client service-worker fallback to return cache immediately and update in background.
Expose Age and Cache-Status headers; record them in RUM and server logs.
Create Prometheus metrics and alerts for stale_served_ratio and revalidation latency.
Build purge/versioning workflow for emergency fixes and CI/CD publications for map style changes.

Quick reference: example headers

Base tile: Cache-Control: public, max-age=86400, stale-while-revalidate=604800
POI tile: Cache-Control: public, max-age=60, stale-while-revalidate=30, stale-if-error=86400
Critical alert: Cache-Control: public, max-age=10, stale-while-revalidate=5

Final considerations

Stale-while-revalidate is not a silver bullet but a practical design pattern for maps in 2026: it keeps maps fast, reduces costs, and—when instrumented properly—keeps data freshness within agreed SLOs. The balance is in defining appropriate SWR windows per layer, exposing age metadata, and wiring observability so you detect and mitigate stale surprises quickly.

Call to action

Ready to reduce origin costs and speed up your map UX without surprising your users? Start with a 2-week pilot: classify layers, deploy SWR for a subset of tiles (POI first), instrument the metrics above, and compare LCP and stale_served_ratio. If you want, run our cache-audit script or get a consultation to map your ideal SWR windows and purging workflows. Visit caching.website/tools or contact our team for a tailored audit.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.