Postcode Lookups

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

The easiest way to interact with the worker is to use the Address Lookup form field. 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 picker drop-down expects an array of address objects 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 - you should write a Handler function to push the address data into the input fields on your form.

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