Data Quality user documentation
home/Address validation/Pro Web/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.

Users can use any mixture of upper and lower case characters, as the Singleline engine does not differentiate between upper and lower case text.

When users submit a search, each component of the entered information becomes a subject of the search.

Method

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 engine to Singleline.
  2. Should the response contain a list of picklist that need further refinement, you can drill down further by stepping into a suggestion or providing a refinement.
    • GET /address/picklist/stepin/v1/{moniker}: Step-in allows a user to select a suggestion and 'step into' it to obtain more detailed picklist.
    • POST /address/picklist/refine/v1/{moniker}: 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.
    • GET /address/format/v1/{moniker}: Formats an address into the specified layout. If no layout is set, the default will be used.

Recommended integrations

Intranet address capture

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 starts to type into the single text box. Suggestions will be displayed in a drop-down.
  2. Optionally, the user can either:
    • Continue to type for a more accurate selection in the drop-down.
    • Provide a refinement for one of the suggestions to create a new list of suggestions (for example, providing a more specific address component like a street or building number).
    • 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 per your website design i.e. a single text box or a multi-fielded layout.

Singleline sequence diagram

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

Singleline developer workflow

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

Public website address capture

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 per your website design i.e. a single text box or a multi-fielded layout.

Singleline sequence diagram

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

Singleline developer workflow

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

Pro Web SOAP enables an untrained user to capture their own address with minimal interaction by entering information into a wizard.

Method

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

Operation SOAP Action Description
1. Can Search DoCanSearch Checks whether the combination of data mapping, engine and layout are valid for search.
2. Initial Search DoSearch Performs the initial search.
3. 'Step In' DoRefine 'Steps into' a picklist that was created during the previous search.
4. Refine DoRefine Refines the picklist that was created during the previous search.
5. Get Final Address DoGetAddress Creates a final formatted address from a previously created picklist item.

Typically, the process of searching with the Singleline engine follows this format:

  1. Pre-search: an optional check on the validity of a search using the DoCanSearch action.
  2. Initial search: the DoSearch action can be used for the initial search. It returns a Picklist object which contains PicklistItems that can be displayed. Each item can remain merely informational, be expanded or formatted into a final address.
  3. Handling picklists and monikers: the picklist items are displayed to the user. Depending on the user's actions, one of the following will occur:
    • The DoRefine action can be used to 'step into' a picklist result (for example, a street name will show a picklist of premises). This hierarchical picklist behavior is the default. If a single flattened picklist is required, the flatten flag has to be set before the initial search is performed.
    • The DoRefine action can be used to narrow down the current picklist to one with a subset of items (for example, using "high" on street names will return another picklist containing only streets starting with "high").
      The DoRefine action is also called in certain special cases. For example, when an item is an unresolvable range (certain countries) or a Phantom Primary Point (AUS only).
    • The DoGetAddress action can be used to format a final address. A call to stepIn, refine or DoGetAddress requires a moniker from either the Picklist or a PicklistItems returned by a previous call. These monikers encode the information required to recreate a particular picklist/picklist item, and are the means by which any integration navigates the search process.
  4. Format the final address: once the final address has been identified, the DoGetAddress action will apply a layout to this item, returning a FormattedAddress object that contains the final formatted address.

Recommended integrations

Intranet address capture

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 per your website design i.e. a single text box or a multi-fielded layout.

Singleline SOAP sequence diagram

Interaction Between Pages and Code

The diagram below shows the interaction between the pages and code for web: address capture. The pages are visited in a sequential manner. When a user clicks the Next button on each page, control is passed to the code relating to the next page. When a user clicks the Back button, control is usually passed to the code preceding the page last visited in order that this page can be displayed.

Error Conditions

If any of the following error conditions occur, control is passed to the "Format Address" code:

  • An error condition is signalled by the server
  • the server cannot be reached
  • there is an error in the integration code
  • the search failed with "Too many matches", or with "no matches", or because of server timeout (the search did not finish within the time limit)

The "Format Address" code enables the display of the Confirm Address page, in which the user can manually enter the required address.

interaction between pages and code

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

Public website address capture

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

The recommended workflow (as demonstrated by our sample code) is:
Singleline developer workflow
The relevant address components can be stored in your database if required.

A partial address consists of one or more address elements, separated by commas. If the organization, house or street name is unusual, one such partial address element might be sufficient to identify the complete address.

Users should never need to enter a full address as Pro Web is designed to identify addresses even when only certain elements of an address are entered, or abbreviated forms of elements, such as "St" and "Rd" are used.

When users enter address elements, if there are any discrepancies between the spelling of the entry and the spelling as recorded in the dataset, Pro Web will usually manage to find the required address.

If a user's search input is not specific enough, the search for matching addresses can take too long or can result in too many addresses to be useful. For example, Green* followed by a town name would retrieve:

  • all matching organizations (Greendwood Motors, Green Acres Health Farm, etc.);
  • all matching building names (Greenford Towers, Greendale Heights, etc.);
  • all matching street names (Green Lane, Greenfield Street, etc.);
  • all matching place names (Greenslopes, Greenwich, etc.).

By identifying which address elements are represented by parts of the address, searches can be made more efficient.

Therefore, users can identify a part of an address as, for example, a street name or an organization name. If a user tags part of the address as a post town, Pro Web only looks through its list of post towns when it endeavors to match that part of the address.

The address elements that can be tagged in the datasets that the user has purchased are explained in the Data Guide supplied with the data.

This type of search usually involves the following stages:

  • Typically, the user enters the address details, in the order that they would appear on an envelope, and performs a search.
  • If more than one possible match is found, the user can select the required address from a picklist.
  • The full address is returned.

For example, to search for 65 Rushton Street, Carnavon, WA (from the Australia data), a user should follow these steps:

  1. Select the Singleline search method.

  2. Select Australia from the Country or Datamap drop-down box.

  3. Type the following search string in the Enter Search field, separating each part with a comma:

    65 Rushton St, Carnarvon, WA

  4. Click Search.

As Pro Web only found one address which precisely matches the search criteria, it returns the address directly to the address edit dialog.

When United Kingdom with Names data is installed, search results will include the names of residents (where known) for each address.
Names are not available for searching on the initial stage, so users cannot enter a name as a search term.

For the United Kingdom with names data the user can search for names information from a picklist of individual addresses. Additionally, the user can search for names information by viewing a list of all Names data for a given street.

Locating Names from an Address Picklist

Users can return Names information for specific addresses, from an address picklist. For example, to search for the resident of 25 Maidstone Road, Swindon, SN1 3NL, a user should follow these steps:

  1. Select the Singleline search method.
  2. Use the Country or Datamap drop-down box to select a data mapping which includes a names additional dataset. In this example, United Kingdom with Names is selected.
  3. Type 25 Maidstone Road, Swindon in the Enter Search field. Click Search. A list of names is returned.
  4. Users can return the full address without a name by clicking the premises number at the top of the list.
  5. Alternatively, users can click on the required resident and the name and full address will be returned.

Locating Names at Street Level

This function enables users to view a list of all the Names data for a given street. The Names information is displayed at street level in a separate list from the premises data.

This is useful if the exact premises or sub-premises address is not known, as the user can typedown on the relevant name to return the correct premises/sub-premises information.

To expand and view Names data at street level, a user should follow these steps:

  1. Select the Singleline search method.

  2. Select United Kingdom with Names from the Country or Datamap drop-down box.

  3. Type valley gardens, wimbledon in the search field, and click Search to display all premises and names data available for the selected street. The list of premises will then be displayed (a list of all Names data for all premises in the given street is displayed in alphabetical order).

    Alternatively a user can type in the name of the resident to return matches with just that name.

  4. Type Believe in the Search field, and click Search to display any residents of the selected address who have the name Believe.

  5. Click the required resident to return their name and full address, including premises information.

This search usually involves the following stages:

  • Typically, the user enters the address details, in the order that they would appear on an envelope, and performs the search.
  • If more than one possible match is found, the user can select the required address from a picklist.
  • Pro Web returns the name and full address.

United Kingdom (Businesses)
In addition, United Kingdom data is available in a Business additional dataset. This enables users to capture address information for United Kingdom businesses.

Business data is provided by the Post Office and by Experian. Users can select which type of business data they want to search on in the Format Options dialog of the Configuration Editor.

To search for a business address in the United Kingdom with Business data, a user should follow these steps:

  1. Select the Singleline search method.
  2. Use the Country or Datamap drop-down box to select a data mapping which includes a Business additional dataset. In this example, United Kingdom with Businesses is selected.
  3. Type Experian, London in the Search field and click Search to display a picklist of matching results.
  4. Click on the required match to return the full business name and address.

If your users are searching for addresses which contain post boxes, such as PO Box in the UK and Roadside Mail Box (RMB) in Australia, the post box number should be preceded with the official post box descriptor for the current dataset. For example, with the Australia data, a user would need to precede the post box number with "RMB".

This will fail if this descriptor is not included as part of the search.

To search for a PO Box address numbered 3376 in Coventry in the United Kingdom, a user should follow these steps:

  1. Select the Singleline search method.
  2. Select United Kingdom data from the Country or Datamap drop-down box.
  3. Type PO BOX 3376, Coventry in the Search field and click Search to return the matching entry.
Pro Web

Address search types