Caching Strategies for Location Lookups

Every UPCS key has an hourly request limit, 1,000 per hour by default. Caching is the easiest way to stay under it and to make your pages faster. The trick is caching the right things for the right time.

What is safe to cache

The same coordinates always give the same code, and a code always refers to the same 3 m by 3 m cell. That makes results from lookup and resolve good cache candidates.

Item	Cache?	Suggested key
Lookup by code	Yes	upcs:lookup:{CODE}
Resolve by coordinates	Yes, rounded	upcs:resolve:{lat6}:{lng6}
Embed session	Briefly	per origin, until near expiry
404 for unknown code	Short only	upcs:lookup:{CODE}:miss
Rate limit errors	No	n/a

Keys and normalisation

Normalise before building a key: uppercase and trim the code, and round coordinates to six decimals. Otherwise equivalent inputs create separate entries and the hit rate drops.

A simple example

const cache = new Map();            // use Redis or similar in production
const TTL = 24 * 60 * 60 * 1000;    // one day

async function cachedLookup(code) {
  const key = 'lookup:' + code.trim().toUpperCase();
  const hit = cache.get(key);
  if (hit && hit.expires > Date.now()) return hit.value;

  const value = await lookup(key.slice(7));   // your server-side lookup function
  if (value) cache.set(key, { value, expires: Date.now() + TTL });
  return value;
}

Cache misses

Cache "not found" for a short time only, perhaps a minute, so a typo does not trigger repeated calls but a code created moments later is still found.

Invalidation

Descriptive fields such as an address label can be edited, so keep a TTL rather than caching indefinitely. If a user edits their location in your system, delete the relevant key.

Do not cache errors blindly

Never cache 401, 403 or 429 responses as if they were data. They indicate configuration or load problems, handled in rate limits and backoff and the error codes reference.

For the embed side, see embed session TTL and renewal.