Skip to content
instantgeo

Caching

Read this one. It is the difference between instantgeo feeling instant and feeling slow.

Why it matters here specifically

Our origin is in Jakarta. The response depends on who is asking, so it is Cache-Control: private — meaning Cloudflare cannot cache it for you and every uncached call is a full round trip to Indonesia. For a visitor in Europe or North America that is roughly 250–350ms.

Cached, it is zero.

We are working on the underlying number. In the meantime, caching is entirely in your hands and takes about five lines.

Cache per session

A visitor’s location does not change while they browse. Look it up once:

async function getGeo(key) {
  const cached = sessionStorage.getItem('geo');
  if (cached) return JSON.parse(cached);


  const geo = await fetch(
    `https://api.instantgeo.info/v1/geo?key=${key}`
  ).then((r) => r.json());


  sessionStorage.setItem('geo', JSON.stringify(geo));
  return geo;
}

A shopper viewing eight pages now makes one request instead of eight. That is an 8x reduction in both latency-visible calls and quota consumption.

The SDK does this plus in-flight deduplication in under 1KB.

Preconnect

<link rel="preconnect" href="https://api.instantgeo.info" />

In your <head>, this opens the TLS connection while the rest of the page loads, so the first call does not pay for the handshake. A cross-continent handshake costs two to three extra round trips — this line is free and removes them from the critical path.

Do not block rendering on it

Never await geolocation before painting. Render a sensible default, then adjust:

// Good: page renders immediately, refines when geo arrives.
document.body.dataset.currency = 'USD';
getGeo(key).then((geo) => {
  if (geo.currency) document.body.dataset.currency = geo.currency;
});
// Bad: every visitor waits on a network call before seeing anything.
const geo = await getGeo(key);
render(geo);

Respect Cache-Control

We send private, max-age=300. If you are calling from a server, honour it. Five minutes is plenty — a caller’s IP rarely moves faster than that, and it cuts your usage substantially.