The Lookup search type is designed to enable the user to enter a key search term to produce the correct address. This search type is only available for use with certain datasets that contain a logical reverse search key.

The user enters the search key and the service returns the address that matches the search key. If the search key matches multiple addresses, a list of suggested addresses 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, as in most cases the search key only matches a single address. 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 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.