Toggle menu

Postcode Lookups

The API Server's Postcode worker can be configured to use a range of providers, each of which returns address information from a given source. 

The easiest way to interact with the worker is to use the address lookup field type. This field includes a text input box (so users can enter their postcode), a search button, and a drop-down list which will be populated with the returned addresses.

There are a wide range of properties, including the ability to hide or disable any of the elements of the field, validate the postcode, choose the provider the field will use, override the worker URL and change the method called, as well as all of the usual hints, error messages, handlers and functions.

Out of the box the address lookup field shows all of its input boxes and buttons, uses an inbuilt drop-down list, will use your Postcode worker's defaultProvider (set in the API Server's configuration file), uses the standard URL (/apiserver/postcode) and calls the postcodeSearch method.

Performing the Search

Clicking the search button performs a postcode search using the custom search(postCode) function. The returned addresses are stored as an array within the FIELDNAME_ADDRESSES variable (where FIELDNAME is the name of your lookup field), accessible via the getAddresses() custom function.

The inbuilt address selection drop-down expects an address that is returned in the following format:

{
    "udprn": "10070767046",
    "company": "",
    "department": "",
    "line1": "24 DARKLAKE VIEW",
    "line2": "",
    "line3": "",
    "line4": "",
    "line5": "",
    "town": "PLYMOUTH",
    "county": "",
    "postcode": "PL6 7TL",
    "ward": "E05002086",
    "location": "",
    "easting": 251483.984375,
    "northing": 60263.73046875,
    "latitude": 50.42340377068654,
    "longitude": -4.092103889615438,
    "custodian": 1160
}

If the data is in this format, the address list drop-down will be automatically populated with the addresses returned from a search.

When a user picks an address from the drop-down a "change" event is fired so that any associated fields can be populated.

The field will also create a set of helper variables corresponding to each line of the selected address:

  • FIELDNAME_UDPRN
  • FIELDNAME_COMPANY
  • FIELDNAME_DEPARTMENT
  • FIELDNAME_LINE1
  • FIELDNAME_LINE2
  • FIELDNAME_LINE3
  • FIELDNAME_LINE4
  • FIELDNAME_LINE5
  • FIELDNAME_TOWN
  • FIELDNAME_COUNTY
  • FIELDNAME_POSTCODE
  • FIELDNAME_WARD
  • FIELDNAME_LOCATION
  • FIELDNAME_EASTING
  • FIELDNAME_NORTHING
  • FIELDNAME_LATITUDE
  • FIELDNAME_LONGITUDE
  • FIELDNAME_CUSTODIAN

Address Data in Different Formats

The lookup field can work with addresses data in any format. However, if your data doesn't follow the above structure, you won't be able to use the inbuilt drop-down selection list. The example form related to this article shows one way around this.

Last modified on 26 May 2022

Share this page

Facebook icon Twitter icon email icon

Print

print icon