The Lookup search type is designed to enable the user to enter a key search term to produce desired address information.

The user enters the search key and the service returns the relevant information for that match. If the search key matches multiple pieces of information, a list of suggestions is returned, from which the user can select the required one. When the user has entered the search key, they should start the search manually.

Lookup normally requires minimal user interaction. However, in some cases it is possible that the search key matches more than one address, in which case a flattened list of suggestions is returned.

This search type is only available for use with certain datasets that contain a logical reverse lookup search key.

Methods

This is a two-step process involving two endpoint methods:

  1. Enter a search key.
    • POST /address/lookup/v1 looks for an address that matches the search key entered.
  2. Format the selected address, using the 'global address key'. You can choose between:
    • GET /address/format/v1/{global_address_key}: Formats an address into the standard 7 line global layout, thereby creating a well formatted address for every country and territory.
    • POST /address/format/v1/{global_address_key}: Formats an address into one of your available custom layouts.

Recommended implementation

  1. The user enters the search key and manually starts a search.
  2. Select a full address from the results.
  3. When a selection is made, the final address is displayed per your website design i.e. a single text box or a multi-fielded layout.

sequence diagram

The recommended workflow (as demonstrated by our sample code) is:

 developer workflow

The relevant address components can be stored in your database if required.

Methods

  1. Enter the type of search key and its value
    • POST /address/lookup/v2 finds all combinations of corresponding locality information for the value entered.
  2. Use the returned suggestions to populate other locality fields on your form.
  3. Optionally, set the Add-addresses header on the lookup request to retrieve a list of addresses that reside within the provided search key. Format the selected address, using the 'global address key'.
    • GET /address/format/v1/{global_address_key}: Formats an address into the standard 7 line global layout, thereby creating a well formatted address for every country and territory.

Recommended implementation

  1. The user enters a single piece of locality information and manually starts a search.
  2. Either select a combination of locality information or a full address from the results.
  3. When the collection of locality information is selected, related fields are pre-filled on your website. Should a final address be selected, it is then displayed per your website design i.e. a single text box or a multi-fielded layout.

sequence diagram

The recommended workflow (as demonstrated by our sample code) is:

developer workflow

The relevant address components can be stored in your database if required.