Postcode Lookup

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.

Providers and Cost

Postcode lookups are answered by one of two services, tried in the order you set. This article explains the two, how to order them, the Google key, and the ceiling that stops a single page view from triggering an unbounded number of lookups.

Where to find it

Architect Panel → Integration & Connections:

• Postcode Lookup — shows the services in order, whether a Google key is set, and lets you test a postcode

The settings themselves are in Site Settings, in the Postcode Lookup group (see Site Settings).

The two services

• postcodes (postcodes.io): free, needs no key, covers UK postcodes only, and answers up to 100 postcodes in one request. Postcodes that do not look like UK ones are never sent to it.
• google (Google Geocoding): one request per postcode, needs a key, is a paid Google service, and is not limited to the UK.

No other services are supported. Any other name in the list is ignored, and a list containing nothing recognisable falls back to postcodes on its own.

Setting the order

1. In Site Settings, Postcode Lookup group, set Services to try, in order as a comma-separated list. It ships as postcodes,google.
2. For each postcode, the services are tried in that order and the first answer wins. A postcode the first service cannot find is passed to the next.
3. To use only the free service, set it to postcodes.

For UK data, keep postcodes first: it answers almost everything, in bulk, and Google only sees what it missed. For data outside the UK, postcodes.io finds nothing, so in practice every lookup goes to Google.

The Google key

Enter the key in Google Geocoding API key. The key must have the Geocoding API enabled in your Google account. If no key is set, the google step is skipped silently, which the Postcode Lookup screen shows as "Not set - the google step is skipped". This is a separate key from any used for maps or address autocomplete in visitors' browsers.

If Google refuses a request (a key that is not authorised, or a quota reached), nothing is cached and the refusal is written to the error log, so the same postcodes are tried again next time. A test on the Postcode Lookup screen reports "No service could find" the postcode.

Limits

• Most postcodes to look up in one go (500): the most postcodes a single page view or warm-up run will look up. On a first visit to a large browse view, postcodes beyond the ceiling wait for later visits; Warm postcode cache in the Browse View Builder fills the rest in batches of the same size.
• Days before a postcode is looked up again (365) and Days before an unknown postcode is tried again (30): how long a cached answer counts as current. See Postcode Lookup and the Cache.

What goes wrong and how to tell

• Non-UK postcodes are never found: Google is not in the list, or no key is set.
• Google usage is higher than expected: Google is listed first, or the data is not UK. Put postcodes first.
• The same failures recur: check the error log for Google refusals and the key's settings in your Google account.

Worked example

A national charity's venues are mostly in the UK, with a few in Ireland. The architect keeps postcodes,google and adds a Google Geocoding key. When the venues view is warmed, postcodes.io resolves the UK venues in a handful of bulk requests and Google answers only the Irish ones. The What Is Cached card's breakdown by service confirms that Google handled a small minority.

Recommendations

• Keep postcodes first for UK data.
• Add Google only if you need it, and watch its usage in your Google account.
• Leave the ceiling at 500 unless pages are slow on first view.
• Test a postcode after any settings change.