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

Singleline

The Singleline search type is optimized for users entering two or more address elements, each separated by a comma, in the order as they would appear on an envelope - starting with the most specific (for example, a building number and/or a street name) and then moves on to more general elements (for example, a town or postcode). When the user has entered all the information, they should start the search manually.

Singleline searches can use a variety of techniques to return the correct address from incomplete or misspelled information. This 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. The search term entered can also contain elements such as wildcards.

A prompt set can be used to guide the user as to what information should be entered at each stage. Ideally, the user will always enter information that generates the smallest number of matches. This makes the search more efficient and makes it easier for the user to select the final address. Which prompt set should be used depends on whether the flatten option is set to true or false.

Methods

This is a multi-step process involving the following endpoints:

  1. Search for an address either partially or in full. This will provide a selection of addresses to choose from.
    • POST /address/search/v1: Set the search_type to singleline via the options array.
  2. Should the response contain a list of suggestions that need further refinement, you can drill down further by stepping into a suggestion or providing a refinement.
    • GET /address/suggestions/stepin/v1/{global_address_key}: Step-in allows a user to select a suggestion and 'step into' it to obtain more detailed suggestions.
    • POST /address/suggestions/refine/v1/{global_address_key}: The user is able to provide additional information for the request, for example to select a single building from building numbers returned in a range.
  3. Repeat the above step as often as necessary until a full address is selected.
  4. 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 integrations

For integrations that target users who are familiar with the address capture process, like call center operators, we recommend setting the flatten option to false. This does not affect the way in which the initial search is performed, but does affect the number and type of suggestions that are returned. The suggestions may have one or more of the following properties:

  • Suggestions can be 'stepped into' to produce a new list of suggestions.
  • Suggestions contain 'informational' items.
  • Suggestions will commonly contain fewer items than if the search was performed with the flatten option set to true, due to a hierarchical nature of the resulting list of suggestions.

We recommend that you use the OneLine prompt set. This prompt set specifies a single unconstrained input line that will accept any address elements. It is designed to be used with the Singleline search type with the flatten option set to false in order to allow users to enter any search terms that they feel are appropriate. Due to the hierarchical nature of resulting list of suggestions, and the fact that the user can step into entries to obtain more detail, there is not a requirement to use a more restrictive prompt sets to minimize suggestions list size.

  1. The user enters the most specific address elements first and manually starts a search.
  2. Optionally, the user can either:
    • Provide a refinement for one of the suggestions to create a new list of suggestions (for example, providing a building number to select a single building from building numbers returned in a range).
    • Step into one of the suggestions to obtain a list of more detailed suggestions.
  3. Repeat the above step as often as necessary until a full address is selected.
  4. Select a full address from the results.
  5. 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.

Singleline sequence diagram showing the refinement process to present a final address to the user, with flatten set to true.

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

Singleline developer workflow showing the API calls, inegration actions, and user actions to get from an inputted address to a final address, with flatten set to true.

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

For integrations that target users who are not familiar with the address capture process, like validating addresses on retail websites, we recommend setting the flatten option to true. This does not affect the way in which the initial search is performed, but does affect the number and type of suggestions that are returned. The suggestions may have one or more of the following properties:

  • Suggestions can't be refined (except for certain special cases).
  • Suggestions don't contain any 'informational' items other than 'No Matches'.
  • Suggestions will commonly contain more items than if the search was performed with the flatten option set to false. This is especially true if the search is not restricted using one of the recommended prompt sets.

When using the Singleline search type and setting the flatten option users are required to input the search terms in a restrictive fashion, in order to generate the smallest number of matches to select from. This is done by using one of the following prompt sets:

  • Optimal
  • Alternate
  • Alternate2 (USA only)
  1. The user enters the most specific address elements first and manually starts a search.
  2. Select a suggestion 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.

Singleline sequence diagram showing the refinement process to present a final address to the user, with flatten set to true.

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

Singleline developer workflow showing the API calls, inegration actions, and user actions to get from an inputted address to a final address, with flatten set to true.

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

Experian Address Validation

Address search types