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.