Depending on your integration and requirements, Address Validate API provides several different ways of searching for addresses:
Singleline searching requires a user to type in two or three address elements, each separated by a comma, in the order, they would appear on an envelope (for example, the street name followed by the town). SingleLine searches can use a variety of techniques to return the correct address from incomplete or misspelled information.
The SingleLine engine 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 SingleLine engine works in the opposite way to the Typedown engine, in that the user enters address elements, starting with the most specific (for example, a house number and/or a street name) and then moves on to more general elements (for example, a town or postcode in the United Kingdom). When the user has entered all the information, they should start the search manually.
The search term entered can 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 engine mode is set to Yes or No.
The SingleLine scenario for address capture commonly requires user interaction after the initial search has been submitted, in order to select a matching address from the returned set of picklist items.
There are two ways in which the engine will return the picklist: in a hierarchical or flattened mode.
Setting the mode
The following diagram demonstrates the flow of searching using this mode:
The shaded boxes represent user actions; all other boxes are integration actions.
The user has control over the address capture process, but this scenario is dependent on:
This scenario is therefore more suitable for internal applications such as an intranet site than for public website address capture.
Searches performed using this mode will create a picklist which may have one or more of the following properties:
The hierarchical mode of the SingleLine engine is designed to allow users to enter any search terms that they feel are appropriate.
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 engine in hierarchical mode (i.e., the Flatten engine option set to False) or the Typedown engine.
Due to the hierarchical nature of the picklist returned, and the fact that the user can step into entries to obtain more detail, there is not a requirement to use the more restrictive prompt sets to minimise picklist size.
Auto step-in functionality is designed to make the address capture process more efficient for users of the SingleLine engine with hierarchical picklists, by reducing the number of interactive steps that the user has to perform to capture an address.
When a search has been performed by the engine, the picklist that is returned contains many properties and flags, some of which correspond to the auto step-in functionality.
These should only be checked after an initial search, and not after the point where a picklist has been displayed to the user for interaction.There are two sets of relevant flags:
stepin action on the first picklist item)format action on the first picklist item)For example, if the user searches against the GBR data for "SW4 0QL", the engine will return a picklist which contains the autostepsafe flag, and a single 100% match.
As this is an exact match to the search term that has been entered, and as the picklist contains the autostepsafe flag, we suggest that the code automatically steps into the first result (an exact match to the search term), without displaying the picklist to the user.
As the previous picklist contains the autoformatsafe flag, we suggest that the code automatically formats the first result to produce only the final address rather than the picklist.
The following diagram demonstrates the flow of searching using this mode:
The shaded boxes represent user actions; all other boxes are integration actions.
This mode is designed to be used within an environment that has the following attributes:
This his scenario is therefore suitable for public website address capture.
Searches performed using this mode will create a picklist which may have one or more of the following properties:
The flattened mode of the SingleLine API is designed to specify 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:
Auto formatting functionality is designed to make the address capture process more efficient for users of the SingleLine engine by reducing the number of interactive steps that the user has to perform.
When a search has been performed by the engine, the picklist that is returned contains many properties and flags, some of which correspond to the auto formatting functionality. These should only be checked after an initial search, and not after the point where a picklist has been displayed to the user for interaction.
When auto-format flags are returned from an address search, we suggest that the Integration code performs a format action on the first picklist item.
For example, if the user searches against the GBR data for "SW4 0QL", the engine will return a picklist which contains the autoformatsafe flag, and a single 100% match.
As this is an exact match to the search term that has been entered, and as the picklist contains the autoformatsafe flag, we suggest that the code automatically formats the first result to produce only the final address rather than the picklist.
Typedown searching starts with the most general address element and, once that has been found, moves on to more specific parts of the address. Typedown is the more useful search option when a user is certain of the address information.
The Typedown engine is designed to allow the user to drill down through a series of picklists to select the required address.
This is the fastest method of searching for address data.
When a user enters text into the search field, the picklist is updated a short period after the user stops typing (this period is currently 300 milliseconds). This means that a picklist is generated as the user types. The more characters that the user enters, the more refinement is shown in the picklist. This 'dynamic refinement' enables searches to be initiated without the user having to type 'Enter' or click the Search button.
Prompt sets are 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.
Typedown searching does not have fuzzy matching capability. Therefore, if you misspell an address element when searching for an address in Typedown, the engine will not be able to find it.
For example, with United Kingdom data, if the user enters "depn", the Typedown search engine cannot find any address elements beginning with that combination of letters and the "No matches" message will be returned. However, deleting the last character will return a choice of places beginning with "dep", and the user can continue searching.
The Typedown method of address capture usually requires user interaction after the initial search has been submitted, in order to select a final address from the returned set of picklist items.
The manner in which the engine will return the picklist is determined by a hierarchical mode of searching.
The shaded boxes represent user actions; all other boxes are integration actions.
The user has control over the address capture process, but this scenario is dependent on:
This scenario is therefore more suitable for internal applications such as an intranet site than for public website address capture.
Searches performed using this mode will create a picklist which may have one or more of the following properties:
Typedown generally involves two, three or four stages. When searching for a United Kingdom address, users should first enter the postcode, county, town or locality.
The Typedown engine usually returns a picklist choice after three or four characters, from which the user can select a place name.
Auto step-in functionality is designed to make the address capture process more efficient with hierarchical picklists by reducing the number of interactive steps that the user has to perform to capture an address.
When a search has been performed by the engine, the picklist that is returned contains many properties and flags, some of which correspond to the auto step-in functionality.
These should only be checked after an initial search, and not after the point where a picklist has been displayed to the user for interaction.There are two sets of relevant flags:
stepin action on the first picklist item)format action on the first picklist item)For example, if the user searches against the GBR data for "SW4 0QL", the engine will return a picklist which contains the autostepsafe flag, and a single 100% match.
As this is an exact match to the search term that has been entered, and as the picklist contains the autostepsafe flag, we suggest that the code automatically steps into the first result (an exact match to the search term), without displaying the picklist to the user.
As the previous picklist contains the autostepsafe flag, we suggest that the code automatically formats the first result to produce only the final address rather than the picklist.
Verification searching requires the user to type in the complete address, as it would appear on an envelope. The entire address is submitted to the engine, and a verification level is returned. The verification level corresponds to the degree of confidence in the returned address. If an accurate match could not be found, the integrator can choose whether to return the address as it was entered by the user or to return a prompt requesting more user interaction.
The Verification engine is designed so that only minimal interaction, or none at all, is required from the user (this can be decided by the integrator).
The user enters the whole address in the same way that it would be written on an envelope, and the entire address is submitted to the engine.
The engine returns a verification level which corresponds to the degree of confidence in the returned (and reformatted) match. For addresses that could not be matched with confidence, it is up to the integrator whether to return a prompt for more user interaction, or whether to return the address as it was entered.
Unlike the other engines, the Verification engine does not require prompt sets to be used to constrain the manner in which the search term is submitted; instead, it expects a complete address to be submitted. The prompt set that should be used for searching with the Verification engine is the Default prompt set which does not apply any restrictions.
There are three ways to use Verification after submitting the search:
The Verification engine may be used with no user interaction required after an initial search has been submitted. This allows an integrator to hide the fact that there is any address management occurring within an application from the user.
This method of using the Verification engine means that addresses that are entered will be simply verified as being correct or not verified as being correct.
If a search results in a VerifyLevel of Verified, VerifiedStreet or VerifiedPlace, then the final formatted address that is returned from the Search call can be used as the captured address. If a search results in any other type of VerifyLevel, then the original address as entered by the user must be used as the captured address.
The Verification engine may be used with minimal user interaction after an initial search has been submitted.
This does not require the display or use of picklists (as with the SingleLine and Typedown engines), but may require a single confirmation by the user if the Verification engine is not highly confident in the match.
This method of using the Verification engine means that addresses that are entered will either be:
If a search results in a VerifyLevel of Verified, VerifiedStreet or VerifiedPlace, then the final formatted address as returned from the Search call can be used as the captured address.
If a search results in a VerifyLevel of InteractionRequired, then the final formatted address as returned from the Search call can be displayed to the user for confirmation. If confirmation is given, then this can be used as the captured address. If confirmation is not given, then the original address as entered by the user can be used as the captured address.
If a search results in any other type of VerifyLevel, then the original address as entered by the user must be used as the captured address.
The Verification engine may be used with full user interaction after an initial search has been submitted. This will require the display and use of picklists for searches that could not locate a single deliverable match.
This method of using the Verification engine means that addresses that are entered will either be:
If a search results in a VerifyLevel of Verified, VerifiedStreet or VerifiedPlace, then the final formatted address as returned from the Search call can be used as the captured address.
If a search results in a VerifyLevel of InteractionRequired, then the final formatted address as returned from the Search call can be displayed to the user for confirmation. If confirmation is given, then this can be used as the captured address. If confirmation is not given, then the original address as entered by the user can be used as the captured address.
If a search results in a VerifyLevel of either StreetPartial, PremisesPartial or Multiple, then the picklist returned can be displayed to the user for use. Picklists are handled in the same manner as with the SingleLine engine, and can similarly function in either hierarchical or flattened mode.
If a search results in a VerifyLevel of None, then the original address as entered by the user must be used as the captured address.
The Verification engine will return one of the following VerifyLevels for a search.
Each level may be treated differently by the integrator depending on the amount of user interaction that is required and indicates the degree of confidence in the returned result.
| Verify | Description |
|---|---|
| None | The searched address could not be matched to any deliverable results in our data. Therefore, address verification is not possible and the provided address should be used. |
| Verified | The searched address was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we correct formatting/spelling errors and add any missing address elements. |
| InteractionRequired | The searched address was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as Verified. |
| Multiple | The searched address was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information for the verification search engine to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a picklist containing all the matches will be returned and the user has to select the required address. If you don't want to use a picklist, the entered address will be used and marked as an unverified match. |
| VerifiedStreet (additional datasets only) | This verification level cannot be returned when using Primary Sourced datasets. The searched address was matched to a single deliverable address in our data but the premise information is missing. This result may be slightly different from the provided address because we correct formatting/spelling errors and add any missing address elements. |
| VerifiedPlace (additional datasets only) | This verification level cannot be returned when using Primary Sourced datasets.The searched address was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we correct formatting/spelling errors and add any missing address elements. |
| PremisesPartial (Primary Sourced datasets only) | This verification level cannot be returned when using additional datasets. The searched address was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a picklist containing all the partial matches will be returned and the user has to select the required address. If you don't want to use a picklist, the entered address will be used and marked as an unverified match. |
| StreetPartial (Primary Sourced datasets only) | This verification level cannot be returned when using additional datasets. The searched address was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a picklist containing all the partial matches will be returned and the user has to select the required address. If you don't want to use a picklist, the entered address will be used and marked as an unverified match. |
Intuitive searching has elements of both SingleLine and Typedown searching. The user enters an address in the format they are familiar with, and with each extra letter typed, the picklist narrows down the result until a final address is selected.
The Intuitive engine is designed so that the user can enter addresses quickly and easily, using a real-time picklist, fuzzy matching and delimiters such as commas and dashes are handled accurately and transparently.
The Intuitive Search engine has aspects of both the SingleLine and Typedown engines in its operation: the user types the address similarly to how they would use the SingleLine engine and selects the correct address from the Typedown style picklist.
Wildcards
The Intuitive search scenario does not require further refinement after the address has been entered as it starts with the most specific address elements. As the user types, the picklist automatically updates with suggestions. The Intuitive Search mode only supports picklists returned in a flattened mode.
The following diagram demonstrates the flow of searching using this mode:
The shaded boxes represent user actions; all other boxes are integration actions.
The first search is performed after a minimum of three alphanumeric characters, not including the Premises or Sub-Premises address elements, have been entered.
From this point a search will be carried out with each additional character added to the input line, though a delay may be set so fast typists do not perform many unnecessary searches.
A picklist will be displayed when an address match is found. This can then be selected and sent to be formatted. Alternatively, if an address is not found or the found addresses are not correct, this address will be classified and standardised.
The Keyfinder engine is designed to enable the user to enter a key search term to produce the correct address.
This engine is only available for use with certain data mappings which include datasets that contain a logical reverse search key.
The Keyfinder engine works in a similar way to the SingleLine engine, in that the user enters the key search term and the engine returns the address that matches the search term. If the key search term matches multiple addresses, a drop-down list of addresses is produced, from which the user can select the required one. When the user has entered the key search term, they should start the search manually.
This search scenario normally requires minimal user interaction, as in most cases the key search term only matches one address. However, in some cases it is possible that the key search term matches more than one address, in which case the engine will return a flattened picklist.
Picklist results for the Keyfinder engine are always returned in flattened mode:
The shaded boxes represent user actions; all other boxes are integration actions.
Special matches
Searches performed using this mode will create a flattened picklist which may have one or more of the following properties: