Postcode Lookup

Postcode Lookup and the Cache

Postcode lookup answers one question — where is this postcode, roughly — and one derived from it: how far apart are these two points.

Where to find it

Architect Panel → Integration & Connections:

• Postcode Lookup — the console — cache size, hit rate, recent misses, clear and warm

Architect Panel → Configuration:

• Site Settings — Look postcodes up, and the provider and cache settings

Architect Panel → Layout & Pages:

• Browse Views — the feature that consumes it

What it is not

It is not a mapping library, an address validator or a routing engine. It does not know what a road is, so every distance it returns is a straight line.

That is worth saying plainly to visitors as well as to yourself. A browse view sorted "nearest first" is sorted by crow-flies distance — which is the right ordering for almost every catalogue and is not the same as drive time. Somewhere across an estuary can be two miles away and forty minutes' drive.

The cache is the point of the feature

A browse view returns the whole table and the front end trims it, so ordering a catalogue by distance means knowing where every row is. Geocoding that on each request would be thousands of outbound calls per page view.

The cache makes it viable, and the key detail is what it is keyed on: the postcode, not the record. A hundred records in the same town share one cache row and one lookup, and the second page view makes no network calls at all.

Unresolvable postcodes are cached too

A postcode that cannot be found is recorded as a negative result rather than simply not stored.

Without that, one bad postcode in a catalogue would re-hit the provider on every single refresh, for ever — and the provider is the one part of this that can be slow or cost money. Negative caching is what stops a single typo becoming a permanent tax on every page view.

Two ages, deliberately different

• Found postcodes are re-checked after a year by default. Postcode coordinates barely move.
• Unknown postcodes are retried after a month, because a genuinely new postcode will eventually start resolving.

It ships switched off

Look postcodes up is off by default, so no installation makes outbound geocoding calls until somebody decides it should. Nothing about a browse view changes until you enable it.

The console

Architect Panel → Integration & Connections → Postcode Lookup shows the cache size and hit rate, the recent misses, and gives you a clear and a warm action.

The recent misses list is the useful one — a run of failures against the same malformed pattern usually means a data quality problem in the source field rather than a provider issue.

Coordinates you already have cost nothing

A Geolocation field already holds coordinates, so records using one need no lookup and no cache entry. Similarly, when a visitor uses their browser's own location, those coordinates are passed straight through rather than being converted back into a postcode and out again.

Worked example

A directory of 4,000 venues across 900 distinct postcodes warms in one pass. The cache holds 900 rows, not 4,000, and a visitor sorting by distance triggers no outbound calls at all. Eleven postcodes fail — all in one imported batch with a transposed character — and appear together in the recent misses list.

Recommendations

• Describe it as straight-line distance wherever visitors see it.
• Warm the cache before the first visitor sorts a large catalogue.
• Read the recent misses as a data quality signal.
• Leave the cache ages alone unless you have a reason.

Providers and Cost

Lookups walk a configured chain of providers and stop at the first that answers for each postcode.

Where to find it

Architect Panel → Configuration:

• Site Settings — Services to try in order, Google Geocoding API key, and the cache and ceiling settings

Architect Panel → Integration & Connections:

• Postcode Lookup — the console, including the warm action

The chain

Services to try, in order is a comma-separated list, shipping as postcodes,google.

• postcodes.io — free, no key, UK only, and it accepts 100 postcodes per call. That bulk endpoint is the whole reason it goes first: a catalogue of several hundred postcodes resolves in a handful of requests rather than several hundred.
• Google Geocoding — one call per postcode, billed, and not limited to the UK.

Leave the free one first

For a UK dataset the first provider will answer almost everything, and Google only sees what it could not. Reversing the order works and costs money for no benefit.

If your data is not UK, the free service will miss most of it and the chain becomes Google in practice — worth knowing before you look at the bill.

Google needs its own key

This catches people out. The existing Google key used for address autocomplete is a browser key and will be restricted by HTTP referrer — a server-side call from your web server is rejected by it.

Google Geocoding API key is a separate setting and needs a separate key, restricted by IP rather than referrer. Do not reuse the address one; it will fail in a way that looks like the provider being down.

The per-request ceiling

Most postcodes to look up in one go bounds how much geocoding a single browse refresh may trigger, shipping at 500.

It exists so the first visitor to sort a large catalogue is not the person who waits for every postcode in it to be resolved. Beyond the ceiling, what was skipped is logged and the request carries on — it is not silently truncated, because a silent truncation reads as "everything was covered" when it was not.

Warming is the real answer

The ceiling makes a large first run survivable; it does not make it good. The Warm postcode cache button on the browse view builder resolves a datastore's postcodes ahead of time, which is what you should do before anybody uses the feature on a big catalogue.

Run it after a bulk import too. A load of two thousand new records is two thousand postcodes the cache has never seen.

Watch the cost, not just the configuration

Billed geocoding is easy to forget about because the cache hides it — after the first pass, usage drops to almost nothing. The moments it rises are a bulk import, a cache clear, or a change of source field. Do those deliberately rather than casually.

Clearing the cache

The console can clear it, optionally per provider. Bear in mind it will be repopulated at whatever the current provider chain and prices are, so clearing a large cache is a billable act if Google is doing the work.

Worked example

An installation leaves the chain at its default. Of 900 UK postcodes, the free service resolves 894 in nine bulk calls; six fall through to Google, which resolves four and fails on two genuinely invalid ones — cached negative. Ongoing cost is effectively nil, and the only spike came from a later import of 1,200 records, warmed deliberately from the builder.

Recommendations

• Keep the free service first for UK data.
• Use a separate, IP-restricted key for Google — never the address autocomplete one.
• Warm after every bulk import.
• Treat a cache clear as a billable action.