The Lookup search type is designed to enable the user to enter a key search term to produce the 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 list of suggestions is returned.
In addition to supporting logical reverse lookups by a search key, /Lookup/v2 adds the ability to determine locality information using just a postal code, and vice versa as well as associating precise what3words locations with geographically close postal addresses.
Locality / postal code conversion
Prefill your form with state, suburb, county and province information from a postal code, or provide your end users with a list of valid postal code and locality combinations to choose from. If you are worried about very common city or town names, the locality combinations are returned based on size / population. For a common town or city name, that means you can present the top combinations to your end users and be confident that the desired combination is included. You also have the option to limit your city or town name search to a specific region or state for more relevant results.
Address Lookup
Instead of searching for an address in the traditional way by typing out the street and premises information, the address lookup functionality allows you to submit related information like a unique key assigned by the postal authority or a what3words location to retrieve associated addresses.
By locality or postal code - Easily lookup up to 1000 addresses in the supplied locality and postal code.
By what3words location - Give your end users an easy way to provide an accurate 3 word address alongside their postal address to ease deliveries.
By utility meter number - Efficiently look up the associated address and enrichment elements to a Meter Point Administration Number (MPAN) or a Meter Point Reference Number (MPRN).
By reverse key - Quickly and accurately look up addresses by their associated keys from authoritative sources. Supply a Unique Delivery Point Reference Number (UDPRN) or Unique Property Reference Number (UPRN) and convert it back to their corresponding postal address.
Availability
What3words, utility meter numbers and reverse key lookups are currently only supported in the United Kingdom.
Pre-filling locality information for the user on your website's form saves the user data entry time, reduces errors and validates that the supplied combination of locality information and postal code is valid. Check out our step-by-step integration overview for the Locality lookup proposition for more detail.
Methods
Search for locality or postal code information by supplying either information partially or in full. This will provide a selection of valid postal code and locality combinations to choose from.
POST /address/lookup/v2: Set the type of the key object to either postal_code or locality depending on your use case.
POST /address/format/v1/{locality_key|postal_code_key}: Set the Add-Enrichment header to true to retrieve the requested Enrichment data.
Credit usage
If you have a per-click license, each successful request to /address/format/v1/ will deduct one or more credits.
Recommended implementation
The user enters a single piece of locality information and manually starts a search. A list of valid locality information data will be displayed in a drop-down depending on your use case.
The end user selects from the results in the drop-down.
Related locality fields can be pre-filled on your website form as well as any optional enrichment information shown per your website design.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
Select which input element you want to use to look up an address:
The Lookup search type can be used to retrieve a list of up to 1000 addresses within the supplied locality or postal code.
Methods
Search for addresses within a specific locality or postal code by supplying either information partially or in full.
POST /address/lookup/v2: Set the type of the key object to either postal_code or locality depending on your use case. Set the Add-Addresses header to true and specify the maximum number of addresses to be returned by using the max_addresses body parameter.
The end user selects an address from the drop down. Retrieve the formatted address and optional enrichment data using the below:
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.
Simultanously retrieve Enrichment data for the selected address in the same format request by setting the Add-Enrichment header to true and specifying the Enrichment attributes you are interested in.
POST /address/format/v1/{locality_key|postal_code_key}: Set the Add-Enrichment header to true to retrieve the requested Enrichment data.
Credit usage
If you have a per-click license, each successful request to /address/lookup/v2 (when setting Add-Addresses header to true) and /address/format/v1/ will deduct one or more credits.
Recommended implementation
The user enters a single piece of locality information and manually starts a search. A list of addresses that are within the supplied locality will be displayed in a drop-down.
The end user selects from the results in the drop-down.
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.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
While what3words is not a traditional reverse geocoding system, combined with Experian Address Validation, it provides a unique and innovative way of associating a user-friendly location description to an address. Check out our step-by-step integration overview for the Reverse geocoding via what3words proposition for more detail.
Methods
Search for an address by supplying either a partial or full 3 word address. Display the list of 3 word addresses in a drop-down.
POST /address/lookup/v2: Set the type of the key object to what3words and pass the end user input as the value.
Retrieve a list of addresses within 100m of the supplied 3 word address.
POST /address/lookup/v2: Set the type of the key object to what3words and pass the full 3 word address with 3 prepended slashes (///) as the value.
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.
Simultanously retrieve the latitude and longitude for the selected 3 word address as well as other Enrichment data for the selected address in the same format request by setting the Add-Enrichment header to true and specifying the Enrichment attributes you are interested in.
Credit usage
If you have a per-click license, each successful request to /address/format/v1/ will deduct one or more credits.
Recommended implementation
The user enters a full or partial what3words address. Suggestions will be displayed in a drop-down.
The user can then either:
Continue to type for a more accurate selection of 3 word addresses in the drop-down.
Select from the results in the drop-down.
When a 3 word address is selected, a list of postal addresses that are within 100m of the geographic location is displayed.
When a selection from the list of addresses 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.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
The Lookup search type can be used as a passive address lookup service when supplying a Meter Point Administration Number (MPAN) or a Meter Point Reference Number (MPRN). Check out our step-by-step integration overview for the Utilities enrichment proposition for more detail.
Methods
Lookup and format an address by providing the type and value of the search key as well as setting the Add-FinalAddress header to true and supplying the associated layout.
POST /address/lookup/v2: Set the type of the key object to either mpan or mprn depending on your use case.
Credit usage
If you have a per-click license, each successful request to /address/lookup/v2 (when setting Add-FinalAddress header to true) will deduct one or more credits.
Recommended implementation
The user enters a utility meter number and manually starts a search.
If a match was found, the fully formatted address is retrieved including all Utility enrichment data and displayed to the user.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
The Lookup search type can be used as a passive address lookup service when supplying a Unique Delivery Point Reference Number (UDPRN) or Unique Property Reference Number (UPRN).
Methods
Look up an address by providing the type and value of the search key as well as setting the Add-Addresses header to true. The 2 available key types are supported by different endpoint versions:
To look up an address based on a UPRN, use POST /address/lookup/v1 and set the type of the key object to default.
To look up an address based on a UDPRN, use POST /address/lookup/v2 and set the type of the key object to udprn.
Retrieve the formatted address and optional enrichment data using the below:
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.
Simultanously retrieve Enrichment data for the selected address in the same format request by setting the Add-Enrichment header to true and specifying the Enrichment attributes you are interested in.
Credit usage
If you have a per-click license, each successful request to /address/lookup/v2 (when setting Add-Addresses header to true) and /address/format/v1/ will deduct one or more credits.
Recommended implementation
The user enters the reverse key to use and manually starts the lookup.
The user selects an address from the drop-down.
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.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
