Loading

Postcode Lookup and the Cache

Postcode lookup turns a postcode into a map position, so browse views can sort by distance, filter to a radius and show a map. Every answer is kept in a shared cache, so each postcode is looked up once rather than every time somebody views a list. Every distance it produces is a straight line, not a driving distance.

Where to find it

Architect Panel → Integration & Connections:

  • Postcode Lookup — the current settings, what is cached, a test lookup and the postcodes that could not be found

Switching it on

  1. Open Site Settings (see Site Settings) and find the Postcode Lookup group.
  2. Turn on Look postcodes up. It ships off, and while it is off nothing new is looked up.
  3. Check Services to try, in order and, if you will use Google, enter the Google Geocoding API key. See Providers.
  4. Save, then open Postcode Lookup and try a postcode.

Lookup is not always needed. A browse view whose location comes from a Geolocation field, or from addresses captured with address autocomplete, already has coordinates, and postcodes already in the cache keep working while lookup is off.

The Postcode Lookup screen

  • Settings: a read-only summary, such as "Looking postcodes up: On", the services in order, whether a Google key is set, and the re-check periods. Change them in Site Settings, under Postcode Lookup.
  • What Is Cached: how many postcodes are cached, how many were found and not found, a breakdown by service and the oldest entry. Buttons: Empty the whole cache, Clear postcodes.io only and Clear Google only.
  • Try a Postcode: type a postcode and click Look it up. It does a live lookup and caches the answer.
  • Postcodes That Could Not Be Found: the 50 most recent misses, with the service asked and when.

How the cache works

  • Keyed on the postcode, in capitals with spaces removed, so "ng15 9fd" and "NG15 9FD" are one entry. The cache is shared by every organisation on the system.
  • Misses are cached too, so an unknown postcode is not asked about again on every page view.
  • Re-check periods: a found postcode is due a fresh lookup after Days before a postcode is looked up again (365), and an unknown one after Days before an unknown postcode is tried again (30). In practice, browse views keep using a found position until it is refreshed by a test lookup, by a visitor typing that postcode, or by Warm postcode cache on a browse view.
  • Failures are not cached. If a service cannot be reached, or Google refuses the request, nothing is stored and the postcode is tried again next time.

To fill the cache for a whole datastore in advance, use Warm postcode cache in the Browse View Builder. See Sorting by Distance.

What goes wrong and how to tell

  • "Postcode lookup is switched off. Turn on 'Look postcodes up' in Site Settings first.": switch it on.
  • "No service could find" a postcode in Try a Postcode: it is mistyped, not a real postcode, or outside the services' coverage. It is now cached as not found.
  • A record never gets a distance: its postcode holds stray punctuation, or is listed under Postcodes That Could Not Be Found. Correct the record.
  • A provider has been changed: clear that provider's entries so postcodes are looked up afresh.

Worked example

A youth service lists 400 activity venues and wants "nearest first". The architect turns on Look postcodes up, tries "NG15 9FD" on the Postcode Lookup screen and sees it found by postcodes.io, then warms the cache from the venues browse view. Three venues appear under Postcodes That Could Not Be Found; two are typos, which the team corrects, and one is a new-build postcode that will be retried after 30 days.

Recommendations

  • Warm the cache when a location view goes live, not on the first visitor's request.
  • Check the not-found list after any large import.
  • Tell visitors distances are straight-line.
  • Do not empty the whole cache casually; every postcode will be looked up again.