Data Quality user documentation
home/Address validation/Experian Address Validation/Address search types/Lookup

Lookup

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 and any optional enrichment information shown per your website design i.e. a single text box or a multi-fielded layout.

Lookup v1 sequence diagram, showing the process of returning an address based on a user search.

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

Lookup v1 developer workflow showing the API calls, inegration actions, and user actions to get from a user search to a final address.

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

Lookup v2 adds the ability to determine locality information, including state, suburb, county and province using just a ZIP or postal code, and vice versa. Plus return up to 1000 addresses in the given locality/postal code.

Secondary search

The customer has the option to search on both city/town names and region/state/province names to perform more accurate searches.

Example

{
    "country_iso": "usa",
    "datasets": [
        "us-address"
    ],
    "key": {
        "type": "locality",
        "value": "Springfield, OR"
    }
}

Availability for secondary searches

Country Available attributes
AUS, CAN,CHN, IRL, JPN, NZL, USA or any other dataset ending in '-eh' Only region is available.
GBR Only town and district are available.

what3words

It can also provide address suggestions using what3words, a popular proprietary geocoding system. User can enter a what3words value for any geographical location* and receive a list of all possible addresses within a 100m radius of that location. User will also receive a list of suggested alternatives using what3words powerful AutoSuggest function.
(* Please note that what3words are currently only supported for locations in the United Kingdom.)

Example

{
    "country_iso": "gbr",
    "datasets": [
        "gb-address"
    ],
    "key": {
        "type": "what3words",
        "value": "///pretty.needed.chill"
    }
}

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'. 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 a single piece of locality information, a utility meter number, a full or partial what3words address and manually starts a search.
  2. Either select a combination of locality information or a full address from the results. For what3words, the value from the AutoSuggest can be used to therefore make a search for addresses within 100m of the suggestion.
  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. For what3words, the final address can be formatted just as for the locality-based search.

Lookup v2 sequence diagram, showing the process of returning an address based on a user search.

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

Lookup v2 developer workflow showing the API calls, inegration actions, and user actions to get from a user search to a final address.

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

Experian Address Validation

Address search types