Address search types

The Experian Address Validation API will use either a partial or complete address to return a list of suggestions. Selecting a suggestion allows the user to then retrieve a well formatted (one that could be printed on an envelope) address.

It is a twostep process including two endpoints:

  1. Search for an address either partially or in full. This will provide a selection of address to choose from.
  2. Format the selected address, using a 'global address key', thereby creating a well formatted address.

Within each search type you have the option to include our data enrichment products to gain an improved level of insight into individuals, households and geographic areas. For example, you can find out an address's geocoordinates. For more information go to our Experian Enrichment article.

There are three main search types that can be used: Autocomplete, Single-field or Multi-field. The API works in the same way backend but works with the search type of your choice to produce a list of results.

The Autocomplete search type is designed so that the user can enter addresses quickly and easily, using a real-time picklist and fuzzy matching, along with Smart Searching in certain countries, while delimiters such as commas and dashes are handled accurately and transparently.

As your end user starts typing an address into a single text box, our API will attempt to Autocomplete by providing a list of addresses that match the current input. Each keystroke will update the list with more accurate suggestions.

Autocomplete sequence diagrams

Autocomplete sequence diagram

Autocomplete user workflow

  1. The user starts to type into the single text box. Suggestions will be displayed in a drop-down.

  2. The end user can then either:

    1. Continue to type for a more refined selection in the drop-down
    2. Select from the results in the drop-down
  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.

Autocomplete developer workflow

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

  1. Make a POST /Search request as the user types into the address capture field. Each request will comprise of the 3-digit ISO code of the country the user is searching on, the current text entered in the field. We recommend that you cancel any unfinished requests upon additional keystrokes.
  2. Display the address suggestions to the user beneath the address capture field. Each suggestion will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in either a single text box or in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.

The Single-Field search type is designed so that the user can enter minimal information in order to produce a list of matching and close-matching addresses from which they can select the required one, when Autocomplete is not desired.

Single-Field searching requires a user to type in two or three address elements. Single-Field searches can use a variety of techniques to return the correct address from incomplete information, including fuzzy matching along with Smart Searching in certain countries.

Single-field sequence diagram

Single-field sequence diagram

Single-field user workflow

  1. The user types an address into the single text box and triggers the validation process (by hitting a button, tabbing out of the last box, pressing enter etc.) . Suggestions will be displayed in a drop-down.
  2. The user selects the correct address
  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.

Single-field developer workflow

The recommended workflow is:

  1. Make a POST /Search request once the user triggers a search. Each request will comprise of the 3-digit ISO code of the country the user is searching on, the current text entered in the field.
  2. Display the address suggestions to the user beneath the address capture field. Each result will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in either a single text box or in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.

The Multi-Field search type is designed so that the user can enter an address into multiple fields and, when searched for, provides an address using fuzzy matching along with Smart Searching in certain countries.

Your end user will enter the address into multiple fields and then signal (for example by clicking a button) the API to search and try to match the address entered. Your end user can then select their address from a list of results provided.

Multi-field sequence diagram

Multi-field sequence diagram

Multi-field user workflow

  1. The user types the address into separate fields.
  2. The user then triggers the validation process (i.e. by hitting a button or tabbing out of the last box).
  3. Suggestions will be displayed in a drop-down.
  4. When a selection is made, the final address is displayed per your website multi-fielded layout.

Multi-field developer workflow

The recommended workflow is:

  1. Make a POST /Search request from combining the text of all the fields (separated by commas).
  2. Display the address suggestions to the user beneath the address capture field. Each result will have a global address key which needs to be held until a selection is made.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form. The API will use the global address key to arrange the address in your own address layout using the returned address elements.
  5. Store the relevant address components in your database if required.