Address Validate SOAP
Overview
Address Validate API provides a SOAP interface for global address searching and validation. We currently support over 160 countries.
This API uses TLS 1.2 encryption. Find out more.
This guide is for integrators who want to access our service directly, instead of using our SOAP sample code. It also assumes that you are familiar with our address search functionality.
Alternatively, REST API is also available for the GBR, USA and CAN datasets.
Workflows
The following operations make up our address search and validation functionality:
| 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. |
The localisation attribute is not used for any of the operations.
Validate one address element at a time
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 behaviour 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.
Validate using the full address
The Verification engine is designed to require minimal, if any, interaction from the user. This can be defined by the integrator.
The user should enter the full address in the same format that they would write it on an envelope, and the entire address is submitted to the engine.
Picklists are only returned by verification searches where the verification level is high enough to match to at least one address, but not high enough to confidently match a single address, for example PremisesPartial, StreetPartial or Multiple.
In such cases, the integrator may decide to offer the user a picklist and let them proceed in a similar fashion to the address search process above or simply to ignore the picklist and use the address as originally entered (in order to minimise user interaction).
The DoCanSearch action may be called for the Verification engine, but it is unlikely that this extra step in the workflow will be useful: the page can simply perform a search and process the results as required.
The typical search process for verification is as follows:
1. Pre-check: an optional check on the validity of a search using the DoCanSearch action.
2. Initial search: call the DoSearch action which returns a SearchResult object that may contain a FormattedAddress object and/or a Picklist object, as well as VerifyLevel.
If picklists are not being handled, the integrator may simply check that the VerifyLevel is high enough before using FormattedAddress.
3. (Optional step) if required, you can handle the picklist using the DoRefine action.
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.
Sample code
To better understand how Address Validate SOAP works, check out our sample code. The sample code guide will help you get set up and test out the API.
Postman collections
We now have pre-configured Postman collections for our APIs.
You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.
Authentication
In order to access address searching and verification functionality, the request has to be authenticated.
Migrated from On Demand?
Your existing integration will not be affected.
Use your current integration username and password or the SAML header. Refer to SOAP sample code for details.
For increased security, you will not be able to change your email/username or the security question.
New user?
Token is a unique alphanumeric code that allows you to use the products covered by your license. It can be retrieved from Self Service Portal > Licenses.
You have to use the provided token:
- Retrieve your token from Self Service Portal > Licenses.
If you don't have one yet, go to Self Service Portal > Licenses, click Add a Token and enter the required details. - Enter your token as the value for "auth-token" field under the HTTP Header.
Refer to sample code for details:
C#
JSP
PHP
Changing integration password
Note that changing the integration password will automatically re-generate the token linked to it which means you may also have to manually modify your setup.
- Go to Self Service Portal > Licenses.
- Click Change integration password.
- Enter a new password and save changes.
- Check your integration for the old password (as it can be hard coded in some files):
- config files
- Javascript
- database
Security
We strongly recommend that you secure your integration to prevent malicious use.
If you don’t specify CORS origin domains, URLs or IPs that will be allowed to use your token, there’s a risk of other websites accessing and using your integration which you may be charged for.
Depending on your setup, you can specify:
- CORS origin domains
Cross Origin Resource Sharing (CORS) is a specification developed by W3C that allows browsers to make cross-domain requests. When making a request to our service, the browser will add an origin request header. Our service will then respond with a CORS specific response header denoting the origin domains allowed to make requests.
To secure your integration, specify the origin domains that will have access to your integration. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five origin domains. - Permitted URLs
If you're integrating your token into a web form, you can also specify the permitted URLs to ensure that only requests from your domains are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five URLs. - Whitelisted IPs/IP ranges
If you're integrating your token to an API service on your server, specify the IP addresses or IP address ranges to ensure that only requests from your servers are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five IPs/IP ranges.
SOAP API Reference
All SOAP endpoints
Please ensure your IT infrastructure allows access to these endpoints (firewall exceptions might need to be added).
We recommend connecting to your regional endpoint (e.g. UK endpoint for UK customers) as that will reduce latency. We also recommend using V3 endpoints, although previous versions are supported as well.
V3: primarily supports token authentication. Username/password and SAML authentication are also supported but not recommended.
| Region | SOAP Endpoint | Port | Protocol |
|---|---|---|---|
| UK/EMEA | https://ws.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx |
|
|
| USA | https://ws2.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx | ||
| APAC | https://ws3.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx |
V2: supports username/password and SAML authentication
| Region | SOAP Endpoint | Port | Protocol |
|---|---|---|---|
| UK/EMEA | https://ws.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx | 443 |
HTTPS |
| USA | https://ws2.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx | ||
| APAC | https://ws3.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx |
V1: supports username/password authentication only
| Region | SOAP Endpoint | Port | Protocol |
|---|---|---|---|
| UK/EMEA | https://ws.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx |
|
|
| USA | https://ws2.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx | ||
| APAC | https://ws3.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx |
Supported versions
- SOAP v1.1 and 1.2
- HTTP v1.0 and 1.1
SOAP actions
The length and format of monikers and IDs are subject to change without prior notice. Caching or validation rules should not be implemented for monikers and IDs.
DoCanSearch
Checks that the combination of data mapping, engine and layout are valid for searching.
This action is performed to check that the combination of data mapping, engine and layout are valid to search on. Only some data mappings can be used with the Verification engine. Layouts can also be defined for specific data mappings, and so may not always be valid for other sets.
Request
Input XML Document: QACanSearch
The DoCanSearch action takes QACanSearch document as input. The properties are as follows:
| Element | Description |
|---|---|
| qas:DataIDType Country |
This defines the data mapping that should be checked against. The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" checks against the United Kingdom. |
| qas:EngineType Engine |
This defines whether the search engine can be used with the data mapping specified previously. The engine options do not have to be specified if this is not required. |
| xs:string Layout |
This is an optional setting. This is used to check whether the layout has been specified. |
Response
Output XML Document: QASearchOK
This document returns information about whether the search parameters that were specified can be used together for searching. The properties are as follows:
| Element | Description |
|---|---|
| xs:boolean IsOK |
This defines whether the search parameters can be used together for searching. |
| ErrorCode |
If IsOk is set to FALSE, this element is present and contains the error code that would be returned in a fault message if a search was attempted. |
| ErrorMessage |
If IsOk is set to FALSE, this element is present and contains the error description that would be returned in a fault message if a search was attempted. |
DoSearch
Submits an initial search to the server.
This action is the first stage of the address capture process and is used to submit an initial search to the server. A search must be performed against a specific data mapping and engine combination and will produce either:
- A formatted final address, with match information;
- A picklist of results from which to choose, with match information.
Request
Input XML document: QASearch
The DoSearch action takes a QASearch document as input. This has the following properties:
| Element | Description |
|---|---|
| qas:DataIDType Country | This defines the data mapping to be used to search against.The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" would search for addresses in the United Kingdom data. |
| qas:EngineType Engine | This defines the search engine to be used to perform the initial search, and the engine options that will be used. |
| xs:string Layout | For Verification searches this element is required, since the result may be returned directly as a final formatted address. This means that you have to specify which layout will be used to format the results. For searches with other engines, this is an optional element. It is used with the AUE dataset to return picklists using the correct Form of address for the layout. |
| xs:string Search | This defines the search string that will be submitted to the server. Different address information should be entered, depending on which search engine is being used. |
Structure: EngineType
The engine type enables you to specify the engine, and any engine options, that will be used to perform the search. This has the following properties:
| Element | Description |
|---|---|
| qas:EngineEnumType Engine Type |
This specifies the engine that will be used to perform the search. The available values are:
|
| xs:boolean Flatten |
This defines whether the search results will be 'flattened' to a single picklist of deliverable results, or output as (potentially multiple) hierarchical picklists of results that can be stepped into. Picklists resulting from searches against Partner Sourced datasets will always be flattened regardless of the setting specified here. |
| qas:ThresholdType Threshold |
This defines the threshold that is used to decide whether results will be returned in the picklist, or whether an informational picklist result will be returned, requiring further refinement. This element is only relevant when using hierarchical mode. The standard setting is 25 items. Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches regardless of the setting specified here.Intuitive specific behaviour:
Due to the algorithms used to return result picklists, this value is used only as an approximation. |
| qas:EngineIntensityType Intensity |
The standard setting is Close. This defines how hard the search engine will work to obtain a match. Higher intensity values may yield more results than lower intensity values, but will also result in longer search times. The available values are:
|
| qas:PromptSetType PromptSet |
The prompt set depends on the search engine used. A prompt set must be used if you are using a Partner Sourced dataset with the Single Line engine. |
| qas:TimeoutType Timeout |
The standard setting is 10000 milliseconds. This defines the time threshold in milliseconds after which a search will abort. A value of 0 signifies that searches will not timeout. The time threshold for searches against Partner Sourced datasets is fixed at 10000 milliseconds, regardless of the setting specified here. |
Response
Output XML Document: QASearchResult
The DoSearch action returns a QASearchResult document, which defines the result of the search process. The verification engine will return results in a different manner to the Single Line and Typedown engines. This has the following properties:
| Element | Description |
|---|---|
| qas:QAPicklistType QAPicklist |
This may not be returned by a search, depending upon the engine and the number of results. |
| qas:QAAddressType QAAddress | This contains a final formatted address result for specific Verification engine result types. |
| qas:VerificationFlagsType VerificationFlags | This contains the matching flags associated with Verification searches. For more information and examples see the USA Data Guide. |
| qas:VerifyLevelType VerifyLevel |
This will only be returned for searches from the Verification engine. The verification level specifies how well the search has been matched, and the appropriate action that can be taken upon the result. |
Structure: QAPicklistType
The picklist type defines a set of result items and properties that are returned from a search. The picklist PicklistEntry will be sorted in the order that the entries must be displayed in. This may not be populated when using the Verification engine, when a formatted address may be instead returned. This has the following properties:
| Element | Description |
|---|---|
| xs:string FullPicklistMoniker |
This is the SPM (search point moniker) that can be used to replicate the given picklist. Full picklist monikers are typically used when you refine a picklist further, using search text to filter the results. Picklist refinement is performed using the SOAP action DoRefine. |
| qas:PicklistEntryType PicklistEntry |
This contains the individual search results as a picklist. Each picklist item represents a separate result and has different information associated with it. |
| xs:string Prompt |
This defines a short text prompt that may be displayed to the user in an interactive scenario. This prompts the user as to what should be entered next. For example: "Enter building number/name or organization". |
| xs:nonNegativeInteger Total |
This defines the total number of results that were matched by the search. This number should only be used for display purposes and should not be assumed to be the size of the returned picklist, which will often contain informational items and is restricted by a threshold. |
| xs:boolean AutoFormatSafe |
Searches that return a single deliverable result will have this element set to TRUE. We recommend that the integrator should automatically format the result without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress. |
| xs:boolean AutoformatPastClose |
Searches that return a single deliverable result, but also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to format the first picklist result automatically, without user interaction, to aid address efficiency. Formatting address results is performed using the SOAP action DoGetAddress. |
| xs:boolean AutoStepInSafe |
Searches that return a single non-deliverable result that can be stepped into will have this element set to TRUE. We recommend that the integration should automatically step into the result, without user interaction. this aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine. |
| xs:boolean AutoStepInPastClose |
Searches that return a single non-deliverable result that can be stepped into, but that also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to step into the first picklist result, without user interaction. This aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine. |
| xs:boolean LargePotential |
Searches that return too many results to be contained in a picklist will have this element set to TRUE. This signifies that further refinement is required before a picklist containing all of the results can be returned. Picklist refinement is performed using the SOAP action DoRefine. |
| xs:boolean MaxMatches |
Searches that produce more than the maximum number of matches allowed will have this element set to TRUE. This signifies that the search was too broad to match and that a new search should be performed with more information specified. |
| xs:boolean MoreOtherMatches |
Searches that produce in excess of the picklist threshold may return a subset of the matches in the picklist, plus an informational picklist item that allows the user to access the others. In this situation, this element is set to TRUE. |
| xs:boolean OverThreshold |
Searches that produce in excess of the picklist threshold may only return a single informational picklist item that allows the user to access the full results. In this situation, this element is set to TRUE. |
| xs:boolean Timeout |
This signifies that the search exceeded the specified timeout value. If this is unexpected for the given search, this could either signify that the timeout is set too low, or that the search was too broad. |
Structure: PicklistEntryType
The PicklistEntryType structure defines the properties of a single picklist result from a search. These are contained in the PicklistType structure. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Moniker |
This is the SPM (search point moniker) that can be used to perform actions upon the picklist item, such as stepping in or formatting the item into a final address. Stepping into picklist items is performed using the SOAP action DoRefine. Formatting picklist items is performed using the SOAP action DoGetAddress. |
| xs:string PartialAddress |
This picklist item is partially formatted into a single string, which may be useful for display in user interactive environments. This string is not suitable to be displayed as the picklist text: the Picklist element must be used instead. |
| xs:string Picklist |
This is the string that must be displayed to the user for the picklist text. This should be combined with the Postcode element. The main picklist text and postcode have been separated to facilitate integration formatting. |
| xs:string Postcode |
This is a postcode string and should be used in conjunction with the Picklistelement, defined previously, for the picklist text. This string is for display purposes only and may be returned blank if no postcode is associated with the picklist string. |
| xs:nonNegativeInteger Score |
This is the percentage score that is given to each match returned from a search. This can be used as a guide to the quality of the match produced. |
| qas:QAAddressType QAAddress |
This is the full formatted address for the picklist entry. This will be null if the search was submitted without the FormattedAddressInPicklist option set, or if the picklist entry does not correspond to a full formatted address. |
| xs:boolean FullAddress |
This element signifies that the picklist item represents a deliverable address. If the user selects this picklist item, then it should be formatted into a final address, indicating the end of the address capture process. Formatting picklist items is performed using the SOAP action DoGetAddress. |
| xs:boolean Multiples |
This element signifies that the picklist item represents multiple addresses, merged into a single entry. This element allows the integrator to display the picklist item with a different icon than a non-multiple entry if required. |
| xs:boolean CanStep |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item can be stepped into, to produce a new picklist with more detail. For example, a picklist item that represents a street can be stepped into to produce a new picklist containing premises within the street. Stepping into picklist items is performed using the SOAP action DoRefine. |
| xs:boolean AliasMatch |
This element signifies that the picklist item has been produced by a match to an alias of the item. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required. |
| xs:boolean PostcodeRecoded |
This element signifies that a postcode was searched on and that the match was made to a newer recorded version of the postcode. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required. |
| xs:boolean CrossBorderMatch |
This element signifies that a place such as a town was searched upon and that the match was made to an adjacent place. This element allows the integrator to display the picklist item with a different icon to a non-alias match if required. Cross Border Matches are only returned from bordering locality matches in the AUS data. |
| xs:boolean DummyPOBox |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item represents a set of PO Boxes. If this entry is stepped into, the resulting picklist will contain all PO Boxes. This element allows the integrator to display the picklist item with a different icon to a normal match if required. |
| xs:boolean Name |
This element is only relevant when searching within data mappings that contain Names information, such as GBN. This element signifies that the picklist item contains names information. It allows the integrator to display the picklist item with a different icon to a non-name match if required. |
| xs:boolean Information |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is an informational item. This means that the entry does not correspond to any particular address item. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry if required. |
| xs:boolean WarnInformation |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is a warning informational item. Unlike a normal informational entry, this will normally be displayed in the picklist when the user should be warned of a situation, such as a search yielding no matches. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry if required. |
| xs:boolean IncompleteAddr |
This element signifies that the picklist item does not contain all of the information required to make it a deliverable address. This is commonly returned when searching within data mappings that do not contain premises information. If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable. |
| xs:boolean UnresolvableRange |
This element signifies that the picklist item is a range of premises which cannot be expanded, due to a lack of information about the possible elements within the range. If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable. |
| xs:boolean PhantomPrimaryPoint |
This element is only relevant when searching within the AUS data. This element signifies that the picklist item is a phantom primary point. A phantom primary point is a premises which is non-deliverable unless the user enters further secondary information. This secondary information may or may not be in the actual data. The user must enter this sub-premises information in order to complete a final address match. If the user selects a picklist item with this element set then they should be further prompted to provide additional premises information so that the address is deliverable. |
Structure: QAAddressType
The QAAddressType structure specifies a formatted address result that is returned directly from a search. This will only occur when the Verification engine is used, and when the search produces one of the following VerifyLevels:
- Verified;
- InteractionRequired.
A search result is formatted using the layout that was specified in the Layout element of the QASearchdocument. When searching using the Single Line engine, and when the Verification engine produces otherVerifyLevels, then this structure will not be returned by the SOAP action DoSearch. The properties are as follows:
| Element | Description |
|---|---|
| qas:AddressLineType AddressLine |
This defines the individually formatted address lines that have been returned by a search. |
| xs:boolean Overflow |
This indicates that some address elements could not fit in the final address and these elements are not displayed (even partially). In order to avoid this, configure the layout to ensure that there are enough lines, and sufficient line width, to accommodate the elements you are returning. This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. |
| xs:boolean Truncated |
This indicates that some address elements could not completely fit on the address line and were cut short. In order to avoid this, configure the layout to ensure that there are enough lines, and sufficient line width, to accommodate the elements you are returning. This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. |
| qas:DPVStatusType DPVStatus |
This returns the DPV status of the server after performing the search. The following values can be returned:
|
| xs:boolean MissingSubPremise |
This attribute indicates that the address is a large volume receiver and may be missing subpremises information. This is currently only relevant when using Canada data. |
Structure: AddressLineType
This structure defines an individually formatted address line and the properties that it contains. This is held in the QAAddresType structure defined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Label |
This defines a text label for the line, which will describe the contents of the line. For example: "Town". Line labels may not be returned if multiple elements are fixed to a single line in the layout. |
| xs:string Line |
This defines the final formatted address line, as described by the layout that was used to format the address result. |
| xs:boolean Overflow |
This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. |
| xs:boolean Truncated |
This element signifies that some address elements were truncated when formatted upon this line. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. |
| qas:LineContentType LineContent |
This describes the elements that are found upon the address line. For example "Name". The following values may be returned:
|
DoRefine
Used to step into and refine a picklist result.
This action is used after a DoSearch action has been performed. It is used to step into a picklist result, and also to refine a picklist.
A picklist item is stepped into when the user selects an entry that can be expanded into elements "beneath" it. For example, a picklist item that represents a street can often be stepped into so that a picklist of the premises beneath the street are displayed. A picklist should be refined when the user enters text to be used to filter the picklist, creating a smaller set of picklist results. For example, a picklist that contains a set of streets can be refined with the text "ba" to generate a new picklist that only contains entries beginning with the letters "ba".
If you wish to step into a picklist result, you should use the SOAP action DoRefine with the picklist item SPM contained within a PicklistEntryType structure, and a blank refinement string.
If you wish to refine the current picklist, you should use the SOAP action DoRefine with the entire picklist SPM contained within a PicklistType structure, and a refinement string that is not blank.
Request
Input XML Document: QARefine
The DoRefine action takes a QARefine document as input. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Moniker |
This is the moniker that will have the action performed upon it. To step into a picklist item, use the moniker returned within the appropriate PicklistEntryType element moniker. To refine a picklist, use the moniker returned from the PicklistType element FullPicklistMoniker. |
| xs:string Refinement |
This is the refinement string to be used. If you are stepping into a picklist item, then this should be blank. |
| xs:string Layout |
For Verification searches this element is required, since the result may be returned directly as a final formatted address. This means that you have to specify which layout will be used to format the results. For searches with other engines this is an optional element. It is used with the AUE dataset to return picklists using the correct Form of address for the layout. |
| xs:boolean FormattedAddressInPicklist |
This specifies whether final addresses should be returned with picklist entries. Searches may be slower with this option, but another server request may not be required. The Layout should be specified if you enable this option. |
| qas:ThresholdType Threshold |
The standard setting is 25 items. This defines the threshold that is used to decide whether results will be returned in the picklist, or whether an informational picklist result will be returned, requiring more refinement. This is an alert box.Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches regardless of the setting specified here. Due to the algorithms used with returning result picklists, this value is used only as an approximation. |
| qas:TimeoutType Timeout |
The standard setting is 10000 milliseconds. This defines the time threshold in milliseconds after which a refinement or stepin will abort. A value of 0 signifies that the action will not timeout. The time threshold for searches against Partner Sourced datasets is fixed at 10000 milliseconds, regardless of the setting specified here. |
Response
Output XML Document: QAPicklist
The picklist type defines a set of result items and properties that are returned from a stepin or refine. The picklist PicklistEntry will be sorted in the order that the entries must be displayed in.
This has the following properties:
| Element | Description |
|---|---|
| xs:string FullPicklistMoniker |
This is the SPM that can be used to replicate the given picklist, without any refinement text that has been specified. Full picklist monikers are typically used when further refining a picklist using search text to filter the results. |
| qas:PicklistEntryType PicklistEntry |
This contains the individual search results as a picklist. Each picklist item represents a separate result, and has different information associated with it. |
| xs:string Prompt |
This defines a short text prompt that may be displayed to the user in an interactive scenario. This prompts the user as to what should be entered next. For example "Enter building number / name or organization". |
| xs:nonNegativeInteger Total |
This defines the total number of results that are present in the picklist. This number should only be used for display purposes and should not be assumed to be the size of the returned picklist, which will often contain informational items and is restricted by a threshold. |
| xs:boolean AutoFormatSafe |
This element will only be specified after stepping into a result. Step-ins that return a single deliverable result will have this element set to TRUE. We recommend that the integrator should automatically format the result without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress. |
| xs:boolean AutoFormatPastClose |
This element will only be specified after stepping into a result. Searches that return a single deliverable result, but also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to format the first picklist result automatically, without user interaction, to aid address efficiency. Formatting address results is performed using the SOAP action DoGetAddress. |
| xs:boolean AutoStepInSafe |
This element will only be specified after stepping into a result. Step-ins that return a single non-deliverable result that can be stepped into will have this element set to TRUE. We recommend that the integration should automatically step into the result, without user interaction. This aids address capture efficiency. Formatting address results is performed using the SOAP action DoGetAddress. |
| xs:boolean AutoStepInPastClose |
This element will only be specified after stepping into a result. Step-ins that return a single non-deliverable result that can be stepped into, but that also produce other lesser matches, will have this element set to TRUE. This signifies that the integrator may choose to step into the first picklist result, without user interaction. This aids address capture efficiency. Stepping into address results is performed using the SOAP action DoRefine. |
| xs:boolean LargePotential |
Searches that return too many results to be contained in a picklist will have this element set to TRUE. This signifies that further refinement is required before a picklist containing all of the results can be returned. Picklist refinement is performed using the SOAP action DoRefine. |
| xs:boolean MaxMatches |
This will only be returned if the user is attempting to refine a picklist that had the MaxMatches element set. Searches that produce more than the maximum number of matches allowed will have this element set to TRUE. This signifies that the search was too broad to match, and that a new search should be performed with more information specified. |
| xs:boolean MoreOtherMatches |
Searches that produce in excess of the picklist threshold may return a subset of the matches in the picklist, plus an informational picklist item that allows the user to access the others. In this situation, this element is set to TRUE. |
| xs:boolean OverThreshold |
Searches that produce in excess of the picklist threshold may only return a single informational picklist item that allows the user to access the full results. In this situation, this element is set to TRUE. |
| xs:boolean Timeout |
This signifies that the stepin or refinement exceeded the specified timeout value. If this is unexpected for the given action, this could either signify that the timeout is set too low, or that the original search was too broad. |
Structure: PicklistEntryType
The PicklistEntryType defines the properties of a single picklist result that is returned from a search. These are contained in the PicklistType structure.
The properties are as follows:
| Element | Description |
|---|---|
| xs:string Moniker |
This is the SPM that can be used to perform actions upon the picklist item, such as stepping in or formatting the item into a final address. Stepping into picklist items is performed using the SOAP action DoRefine. Formatting picklist items is performed using the SOAP action DoGetAddress. |
| xs:string PartialAddress |
This picklist item is partially formatted into a single string, which may be useful for display in user interactive environments. This string is not suitable to be displayed as the picklist text: the Picklist element must be used instead. |
| xs:string Picklist |
This is the string that must be displayed to the user for the picklist text. This should be combined with the Postcode element. The main picklist text and postcode have been separated to facilitate integration formatting. |
| xs:string Postcode |
This is a postcode string and should be used in conjunction with the Picklistelement, defined previously, for the picklist text. This string is for display purposes only, and may be returned blank if no postcode is associated with the picklist string. |
| xs:nonNegativeInteger Score |
This is the percentage score that is given to each match returned from a search. This can be used as a guide to the quality of the match produced. |
| qas:QAAddressType QAAddress |
This is the full formatted address for the picklist entry. This will be null if the search was submitted without the FormattedAddressInPicklist option set, or if the picklist entry does not correspond to a full formatted address. |
| xs:boolean FullAddress |
This element signifies that the picklist item represents a deliverable address. If the user selects this picklist item, then it should be formatted into a final address, indicating the end of the address capture process. Formatting picklist items is performed using the SOAP action DoGetAddress. |
| xs:boolean Multiples |
This element signifies that the picklist item represents multiple addresses, merged into a single entry. This element allows the integrator to display the picklist item with a different icon than a non-multiple entry, if required. |
| xs:boolean CanStep |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item can be stepped into, to produce a new picklist with more detail. For example, a picklist item that represents a street can be stepped into to produce a new picklist containing premises within the street. Stepping into picklist items is performed using the SOAP action DoRefine. |
| xs:boolean AliasMatch |
This element signifies that the picklist item has been produced by a match to an alias of the item. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required. |
| xs:boolean PostcodeRecoded |
This element signifies that a postcode was searched on, and that the match was made to a newer recoded version of the postcode. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required. |
| xs:boolean CrossBorderMatch |
This element signifies that a place such as a town was searched upon, and that the match was made to an adjacent place. This element allows the integrator to display the picklist item with a different icon to a non-alias match, if required. Cross Border Matches are only returned from bordering locality matches in the AUS data. |
| xs:boolean DummyPOBox |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item represents a set of PO Boxes. If this entry is stepped into, the resulting picklist will contain all PO Boxes. This element allows the integrator to display the picklist item with a different icon to a normal match, if required. |
| xs:boolean Name |
This element is only relevant when searching within data mappings that contain Names information, such as GBN. This element signifies that the picklist item contains names information. It allows the integrator to display the picklist item with a different icon to a non-name match, if required. |
| xs:boolean Information |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is an informational item. This means that the entry does not correspond to any particular address item. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry, if required. |
| xs:boolean WarnInformation |
This element is only relevant when searching with the engine option Flatten set to FALSE. This element signifies that the picklist item is a warning informational item. Unlike a normal informational entry, this will normally be displayed in the picklist when the user should be warned of a situation, such as a search yielding no matches. Informational picklist items are designed to help the user complete the address capture process, and must be displayed in the picklist. This element allows the integrator to display the picklist item with a different icon to a noninformational entry, if required. |
| xs:boolean IncompleteAddr |
This element signifies that the picklist item does not contain all of the information required to make it a deliverable address. This is commonly returned when searching within data mappings that do not contain premises information. This element will not be set for searches against Partner Sourced datasets. If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable. |
| xs:boolean UnresolvableRange |
This element signifies that the picklist item is a range of premises which cannot be expanded, due to a lack of information about the possible elements within the range. This element will not be set for searches against Partner Sourced datasets.If the user selects a picklist item with this element set, then they should be further prompted to provide additional premises information so that the address is deliverable. |
| xs:boolean PhantomPrimaryPoint |
This element is only relevant when searching within the AUS data. This element signifies that the picklist item is a phantom primary point. A phantom primary point is a premises which is non-deliverable unless the user enters further secondary information. This secondary information may or may not be in the actual data. The user must enter this sub-premises information in order to complete a final address match. If the user selects a picklist item with this element set then they should be further prompted to provide additional premises information so that the address is deliverable. |
DoGetAddress
Formats a picklist item to obtain a final, formatted address.
This action is performed to format a picklist item in order to obtain the final formatted address. This will typically be when the user selects a picklist item that has the FullAddress element set to TRUE in the associated PicklistEntryType structure.
The formatting of a picklist item is performed using the SPM of the specified picklist item. This is contained within the Moniker element of the PicklistEntryType structure. A picklist item is formatted against a specified layout.
Request
The DoGetAddress SOAP action takes a QAGetAddress document as input. This has the following properties:
| Element | Description |
|---|---|
| xs:string Layout |
This defines the layout that will be used to format the SPM. |
| xs:string Moniker |
The defines the SPM of the picklist item that will be formatted. This is contained within the Moniker element of the PicklistEntryType structure. |
Response
Output XML Document: QAAddressType
The QAAddressType structure specifies a formatted address result that is returned from a DoGetAddressaction. The properties are as follows:
| Element | Description |
|---|---|
| qas:AddressLineType AddressLine |
This defines the individual formatted address lines that have been returned by a search. |
| xs:boolean Overflow |
This element signifies that there were not enough layout lines to contain all of the address line, and that some elements had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths. This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. |
| xs:boolean Truncated |
This element signifies that some of the address lines were too short to accommodate all of the formatted address, and so truncation has occurred. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. This property is not available when you are using Partner Sourced datasets, and a value of "False" is always returned. |
| qas:DPVStatusType DPVStatus |
This returns the DPV status of the server after performing the search. The following values can be returned:
|
| xs:boolean MissingSubPremise |
This is currently only relevant when using Canada data. This attribute indicates that the address is a large volume receiver and may be missing subpremises information. |
Structure: AddressLineType
This structure defines an individually formatted address line, and the properties that it contains. This is held in the QAAddressType structure outlined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Label |
This defines a text label for the line, which will describe the contents of the line. For example "Town". Line labels may not be returned if multiple elements are fixed to a single line in the layout. |
| xs:string Line |
This defines the final formatted address line, as described by the layout that was used to format the address result. |
| xs:boolean Overflow |
This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. |
| xs:boolean Truncated |
This element signifies that some address elements were truncated when formatted upon this line. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. |
| qas:LineContentType LineContent |
This describes the elements that are found upon the address line. For example "Name". The following values may be returned:
|
| qas:DataPlusGroupType DataplusGroup |
This contains any groups of multiple DataPlus items that are associated with the line, broken down into individual DataPlus items. |
Structure: DataPlusGroupType
This structure contains any groups of multiple DataPlus items that are associated with the formatted address line. This is held in the AddressLineType structure outlined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string DataPlusGroupItem |
This element contains a single DataPlus value. |
| Attribute | Description |
|---|---|
| xs:string GroupName |
DataPlus values are grouped according to the DataPlus set they belong to. GroupName identifies the source DataPlus set. |
The following shows an extract of an AddressLine SOAP message returned by the server when both Gas and Electricity meter numbers are configured to appear on the same address line:
<qas:AddressLine LineContent="DataPlus" Truncated="True"> <qas:Label>Gas and Electricity Meter Numbers</qas:Label> <qas:Line>2408630034|2408630036,1508436932|1508436943</qas:Line> <qas:DataplusGroup GroupName="GBRGAS"> <qas:DataplusGroupItem>2408630034</qas:DataplusGroupItem> <qas:DataplusGroupItem>2408630036</qas:DataplusGroupItem> </qas:DataplusGroup> <qas:DataplusGroup GroupName="GBRELC"> <qas:DataplusGroupItem>1508436932</qas:DataplusGroupItem> <qas:DataplusGroupItem>1508436943</qas:DataplusGroupItem> </qas:DataplusGroup> </qas:AddressLine>
DoGetData
Obtains a list of available data mappings.
This action is performed to obtain a list of available data mappings that can be searched on. Specifically, this action will return a set of qas:DataIDType elements that are valid to be passed to the DoSearch action.
Request
Input XML Document: None
There is no XML document that needs to be passed for this SOAP action.
Response
Output XML Document: QAData
The DoGetData action returns a QAData document which defines all of the available data mappings that can be searched against. The properties are as follows:
| Element | Description |
|---|---|
| qas:QADataSet DataSet | This defines the data mappings that are available for searching. |
Structure: QADataSet
This structure contains information about a specific data mapping that can be searched on. This is held in the QAData structure, defined previously. The structure has the following properties:
| Element | Description |
|---|---|
| qas:DataIDType ID |
This defines the data mapping identifier. This is the string that should be passed in the Country element of the QASearch structure for the DoSearch action. For example, "AUS". |
| xs:string Name |
This defines the name of the data mapping as text that can be displayed to users. This allows users to select the data mapping they will search against. For example, "Australia". This string is defined within the DataMappings configuration setting. |
DoGetSystemInfo
Obtains information about the server.
This action is performed to access a list of system information text which may be useful to integrators.
Request
Input XML Document: None
There is no XML document that needs to be passed for this SOAP action.
Response
Output XML Document: QASystemInfo
This structure gives system information about the server. The properties are as follows:
| Element | Description |
|---|---|
| xs:string SystemInfo |
This contains the individual lines of the system information for integrators. The lines are returned with a tab character to allow the integrator to separate keywords from values if required. |
DoGetExampleAddresses
Returns fully formatted example addresses.
This action is performed to return fully formatted example addresses. This may commonly be used to preview a given layout with a set of addresses.
Not all Partner Sourced datasets are supplied with example addresses. Please check the relevant data guide for more information on which datasets support example addresses.
Request
Input XML Document: QAGetExampleAddresses
The DoGetExampleAddresses action takes a QAGetExampleAddresses document as input. The properties are as follows:
| Element | Description |
|---|---|
| qas:DataIDType Country |
This defines the data mapping that you want to return example addresses for. The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" will obtain example addresses for the United Kingdom. |
| xs:string Layout |
This specifies the layout that will be used to format the example addresses. |
Response
Output XML Document: QAExampleAddresses
This document returns all of the example addresses for a given country, formatted using the specified layout. The properties are as follows:
| Element | Description |
|---|---|
| qas:ExampleAddress ExampleAddress |
This contains the set of example addresses. |
Structure: QAExampleAddress
This structure contains a single formatted example address. The structure is contained within a QAExampleAddresses document, defined previously. The properties are as follows:
| Element | Description |
|---|---|
| qas:QAAddressType Address |
This contains the formatted example address. |
| xs:string Comment |
This contains a text description of the example address. For example "A typical residential address". |
Structure: QAAddressType
The QAAddressType structure specifies a formatted address result that is returned from a DoGetAddress action.
The properties are as follows:
| Element | Description |
|---|---|
| qas:AddressLineType AddressLine |
This defines the individually formatted address lines that have been returned by a search. |
| xs:boolean Overflow |
This element signifies that there were not enough layout lines to contain all of the address line, and that some elements had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. This property is not available when using Partner Sourced datasets, and a value of "False" is always returned. |
| xs:boolean Truncated |
This element signifies that some of the address lines were too short to accommodate all of the formatted address, and so truncation has occurred. If this element is set, then you should either add more output address lines in the specified layout, or specify larger widths. This property is not available when using Partner Sourced datasets, and a value of "False" is always returned. |
| qas:DPVStatusType DPVStatus |
This returns the DPV status of the server after performing the search. The following values can be returned:
|
Structure: AddressLineType
This structure defines an individually formatted address line and the properties that it contains. This is held in the QAAddressType structure defined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Label |
This defines a text label for the line, which will describe the contents of the line. For example "Town". Line labels may not be returned if multiple elements are fixed to a single line in the layout. |
| xs:string Line |
This defines the final formatted address line, as described by the layout that was used to format the address result. |
| xs:boolean Overflow |
This element signifies that some address elements could not be formatted upon this line, and so had to overflow onto other lines. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths. |
| xs:boolean Truncated |
This element signifies that some address elements were truncated when formatted upon this line. If this element is set, then you should either add more output address lines in the specified layout or specify larger widths. |
| qas:LineContentType LineContent |
This describes the elements that are found upon the address line. For example "Name". The following values may be returned:
|
DoGetLayouts
Obtains a list of layouts that have been configured within the configuration file.
This action is performed to obtain a list of layouts that have been configured within the configuration file, and can be used to format address results.
A list of layouts is useful for situations where the integration would give the user a choice of which layout to use to format an address result. If only one layout is ever used within an integration, it is more common to code the layout name.
Request
Input XML Document: QAGetLayouts
The DoGetLayouts action takes a QAGetLayouts document as input. The properties are as follows:
| Element | Description |
|---|---|
| qas:DataIDType Country |
This defines the data mapping for which the returned layouts are valid. The available data mappings can be accessed using the SOAP action DoGetData. |
Response
Output XML Document: QALayouts
This document returns all of the layouts that are valid to be used against the provided data mapping. The properties are as follows:
| Element | Description |
|---|---|
| qas:QALayout Layout |
This contains the set of layouts that are valid. |
Structure: QALayout
This structure contains the information about a specific layout. The layouts are contained within the QALayouts document, defined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string Name |
This returns the name of a layout. The name of a layout is defined by the configuration section that it is defined within. The layout name needs to be passed to format a picklist item, using the DoGetAddress action. |
| xs:string Comment |
This returns the layout description. Layouts can have comments defined using the configuration setting Comment. |
DoGetPromptSet
Obtains information regarding a prompt set.
This action obtains information regarding a prompt set, such as the number of lines and the suggested input.
Prompt sets are employed to manage the way in which users enter addresses. An address can be submitted as one or as many text fields; a prompt set defines which address elements can be entered in each field. E.g.: a text field might be constrained so that it only accepts postcodes.
For example, the alternate prompt set for GBR has three input lines:
- Building number or name
- Street
- Town
While the alternate prompt set for USA has four input lines:
- Street address
- City
- State
- ZIP Code
Request
Input XML Document: QAGetPromptSet
The DoGetPromptSet action takes a QAGetPromptSet document as input. The properties are as follows:
| Element | Description |
|---|---|
| qas:PromptSetType PromptSet |
This defines the prompt set that you wish to obtain information about. The available prompt sets are:
|
| qas:DataIDType Country |
This defines the data mapping that will be used to search against. The available data mappings can be accessed using the SOAP action DoGetData. For example, "GBR" returns information about the prompt set suitable for searching within United Kingdom data. |
| qas:EngineType |
This specifies the engine type to be used to perform the subsequent search. |
Response
Output XML Document: QAPromptSet
This document returns information about the specific prompt set that was requested with the country. The properties are as follows:
| Element | Description |
|---|---|
| qas:PromptLine Line |
This defines the set of lines that the prompt set contains. Each prompt set line should correspond to a separate input field for the user to enter their search terms. |
| Attribute | Description |
|---|---|
| xs:boolean Dynamic |
This returns true if the specified search engine requires dynamic refinement at the first search stage. |
Structure: PromptLine
This structure contains information regarding a specific prompt set line. this is contained within the QAPromptSet document defined previously. The properties are as follows:
| Element | Description |
|---|---|
| xs:string PromptLine |
This provides a text hint about what should be entered into the input field associated with this prompt line. For example, "Building number or name". |
| xs:nonNegativeInteger SuggestedInputLength |
This provides the suggested maximum length of the input field. |
| xs:string Example |
This provides an example of what could be entered into the prompt line, to aid the user. For example, "12". |
List of examples
CanSearch
An optional stage of the address search process is to check that the combination of data mapping, engine and layout is valid by using the DoCanSearch action.
This is an essential stage if you are using metered datasets. The operation returns an error if the value of the meter is less than or equal to zero.
| SOAP Action | Input XML Document | Output XML Document |
|---|---|---|
| /DoCanSearch | QACanSearch | QASearchOK |
Description
Returns False if you specify a data mapping:
- that is not supported
- for which you do not have a valid licence
- for which the specified layout has not been defined (specifying a layout is optional)
It also returns False if the credits have run out, or if the requested engine is not appropriate or available (for example, verification is only available for some data mappings).
The operation also returns information as to why a value of False was returned.
Example
The following example shows the combination of the GBR data mapping, Single Line engine and the layout "QADefault" being verified as valid.
Request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
<soapenv:Header>
<ond:QAQueryHeader>
<ond:QAAuthentication>
<ond:Username />
<ond:Password />
</ond:QAAuthentication>
<ond:Security>
<!--You may enter ANY elements at this point-->
</ond:Security>
</ond:QAQueryHeader>
</soapenv:Header>
<soapenv:Body>
<ond:QACanSearch>
<ond:Country>GBR</ond:Country>
<ond:Engine>Singleline</ond:Engine>
<!--Optional:-->
<ond:Layout>QADefault</ond:Layout>
</ond:QACanSearch>
</soapenv:Body>
</soapenv:Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Header>
<QAInformation xmlns="http://www.qas.com/OnDemand-2011-03">
<StateTransition>Unknown</StateTransition>
<CreditsUsed>0</CreditsUsed>
</QAInformation>
</soap:Header>
<soap:Body>
<QASearchOk xmlns="http://www.qas.com/OnDemand-2011-03">
<IsOk>true</IsOk>
</QASearchOk>
</soap:Body>
</soap:Envelope>
Initial Search
The next stage is to submit an initial search to the server using the DoSearch action.
| SOAP Action | Input XML Document | Output XML Document |
|---|---|---|
| /DoSearch | QASearch | QASearchResult |
Description
Performs an address search that returns one or more results. Result(s) can be in the form of a picklist or a single final address.
Example
The following example submits the search string "s87bw" against the GBR data using the Single Line engine, and specifies the "( QAS Standard Layout )" layout. The response is in the form of a picklist item consisting of a single entry.
Request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
<soapenv:Header>
<ond:QAQueryHeader>
<ond:QAAuthentication>
<ond:Username />
<ond:Password />
</ond:QAAuthentication>
<ond:Security>
<!--You may enter ANY elements at this point-->
</ond:Security>
</ond:QAQueryHeader>
</soapenv:Header>
<soapenv:Body>
<ond:QASearch>
<ond:Country>USA</ond:Country>
<ond:Engine>Singleline</ond:Engine>
<!--Optional:-->
<ond:Layout>QADefault</ond:Layout>
<ond:Search>1 alpine ave,10301</ond:Search>
<!--Optional:-->
<ond:FormattedAddressInPicklist>false</ond:FormattedAddressInPicklist>
</ond:QASearch>
</soapenv:Body>
</soapenv:Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Header>
<QAInformation xmlns="http://www.qas.com/OnDemand-2011-03">
<StateTransition>PickList</StateTransition>
<CreditsUsed>0</CreditsUsed>
</QAInformation>
</soap:Header>
<soap:Body>
<QASearchResult xmlns="http://www.qas.com/OnDemand-2011-03">
<QAPicklist AutoFormatSafe="true">
<FullPicklistMoniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|6MUSADwvfBwEBAQABAAWcHJ4AAAAAADEAZA--</FullPicklistMoniker>
<PicklistEntry FullAddress="true">
<Moniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|vOUSADwvfBwEDAQAFnByeAAAAAAAxAGQA</Moniker>
<PartialAddress>1 Alpine Ave, Staten Island NY 10301-4001</PartialAddress>
<Picklist>1 Alpine Ave, Staten Island NY</Picklist>
<Postcode>10301-4001</Postcode>
<Score>100</Score>
</PicklistEntry>
<Prompt>Enter selection</Prompt>
<Total>1</Total>
</QAPicklist>
<VerificationFlags>
<PostCodeCorrected>true</PostCodeCorrected>
</VerificationFlags>
</QASearchResult>
</soap:Body>
</soap:Envelope>
'Step In'
If you want to 'step into' a picklist result, you should use the DoRefine action with the picklist item SPM (Search Point Moniker - used to store the state of a search that is in progress; each picklist item has a SPM) contained within a PicklistEntryType structure and a blank refinement string.
| SOAP Action | Input XML Document | Output XML Document |
|---|---|---|
| /DoRefine | QARefine | QAPicklist |
Description
Refines a picklist that was created during a search.
Example
The following example shows a refinement request using a moniker (name used to uniquely identify each object) returned from the initial search example. The refinement request consists of the street picklist item for "Westwick Road" moniker and the refinement text is blank. The response is in the form of a picklist item containing 3 entries.
Request
POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 374
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soapenv:Header>
<ond:QAAuthentication>
<ond:Username>572c3-8b4</ond:Username>
<ond:Password>YourPassw0rd</ond:Password>
</ond:QAAuthentication>
</soapenv:Header>
<soap:Body>
<QARefine Threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01">
<Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</Moniker>
<Refinement/>
</QARefine>
</soap:Body>
</soap:Envelope>
Response
HTTP/1.0 200 OK Content-Length: 1339 Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <QAInformation xmlns="http://www.qas.com/OnDemand-2010-01"> <CreditsUsed>1</CreditsUsed> </QAInformation> </soap:Header> <soap:Body> <qas:QAPicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01"> <qas:Total>3</qas:Total> <qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker> <qas:Prompt>Enter building number/name or organisation</qas:Prompt> <qas:PicklistEntry Multiples="true" CanStep="true"> <qas:Picklist>121 ... 161 [odd]</qas:Picklist> <qas:PartialAddress>Westwick Road, SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>dOGBREwPUBwMBAAEQeX_AAAA-</qas:Moniker> </qas:PicklistEntry> <qas:PicklistEntry FullAddress="true"> <qas:Picklist>161a</qas:Picklist> <qas:PartialAddress>161a Westwick Road,SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>0OGBREwPUBwMBAAEQeYYAAAA-</qas:Moniker> </qas:PicklistEntry> <qas:PicklistEntry Multiples="true" CanStep="true"> <qas:Picklist>163 ... 207 [odd]</qas:Picklist> <qas:PartialAddress>Westwick Road, SHEFFIELD, S8 7BW</qas:PartialAddress> <qas:Score>0</qas:Score> <qas:Moniker>HOGBREwPUBwMBAAEQeYdAAAA-</qas:Moniker> </qas:PicklistEntry> </qas:QAPicklist> </soap:Body> </soap:Envelope>
Refine
If you want to refine a picklist, you should use the DoRefine action with the full picklist moniker contained within a picklist structure and a non-blank refinement string.
| SOAP Action | Input XML Document | Output XML Document |
|---|---|---|
| /DoRefine | QARefine | QAPicklist |
Description
Refines a picklist that was created during a search.
Example
Continuing from the above 'step in' example, the user has entered refinement text of "205". In this case, the refinement request uses the moniker of the full picklist from the previous operation and the refinement text "205" in the refinement field. The response is a picklist item containing a single entry.
Request
POST / HTTP/1.0 Content-Type: text/xml Content-Length: 388 SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"
<?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soapenv:Header> <ond:QAAuthentication> <ond:Username>572c3-8b4</ond:Username> <ond:Password>YourPassw0rd</ond:Password> </ond:QAAuthentication> </soapenv:Header> <soap:Body> <QARefine Threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01"> <Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</Moniker> <Refinement>205</Refinement> </QARefine> </soap:Body> </soap:Envelope>
Response
HTTP/1.0 200 OK
Content-Length: 705
Content-Type: text/xml
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<QAInformation xmlns="http://www.qas.com/OnDemand-2010-01">
<CreditsUsed>1</CreditsUsed>
</QAInformation>
</soap:Header>
<soap:Body>
<qas:QAPicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01">
<qas:Total>1</qas:Total>
<qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker>
<qas:Prompt>Enter building number/name or organisation</qas:Prompt>
<qas:PicklistEntry FullAddress="true">
<qas:Picklist>205</qas:Picklist>
<qas:PartialAddress>205 Westwick Road,SHEFFIELD, S8 7BW</qas:PartialAddress>
<qas:Score>0</qas:Score>
<qas:Moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</qas:Moniker>
</qas:PicklistEntry>
</qas:QAPicklist>
</soap:Body>
</soap:Envelope>
Get Final Address
The last stage is to obtain the final address using the DoGetAddress action. As input, the picklist item SPM of the PicklistEntry that you want to format should be passed.
| SOAP Action | Input XML Document | Output XML Document |
|---|---|---|
| /DoGetAddress | QAGetAddress | QAAddress |
Description
Creates a final, formatted address from a previously-created picklist item.
Example
Continuing from the above refine example, the moniker of the single picklist entry for "205 Westwick Road" is passed along with the "QADefault" layout. The response contains the address formatted according to the specified layout.
Request
POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 383
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoGetAddress"
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soapenv:Header>
<ond:QAAuthentication>
<ond:Username>572c3-8b4</ond:Username>
<ond:Password>YourPassw0rd</ond:Password>
</ond:QAAuthentication>
</soapenv:Header>
<soap:Body>
<QAGetAddress xmlns="http://www.qas.com/OnDemand-2010-01">
<Moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</Moniker>
<Layout>QADefault</Layout>
</QAGetAddress>
</soap:Body>
</soap:Envelope>
Response
HTTP/1.0 200 OK
Content-Length: 927
Content-Type: text/xml
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<QAInformation xmlns="http://www.qas.com/OnDemand-2010-01">
<CreditsUsed>1</CreditsUsed>
</QAInformation>
</soap:Header>
<soap:Body>
<qas:QAAddress xmlns:qas="http://www.qas.com/OnDemand-2010-01">
<qas:AddressLine LineContent="None">
<qas:Label></qas:Label>
<qas:Line>205 Westwick Road</qas:Line>
</qas:AddressLine>
<qas:AddressLine LineContent="None">
<qas:Label></qas:Label>
<qas:Line></qas:Line>
</qas:AddressLine>
<qas:AddressLine LineContent="Address">
<qas:Label>Town</qas:Label>
<qas:Line>SHEFFIELD</qas:Line>
</qas:AddressLine>
<qas:AddressLine LineContent="Address">
<qas:Label>County</qas:Label>
<qas:Line></qas:Line>
</qas:AddressLine>
<qas:AddressLine LineContent="Address">
<qas:Label>Postcode</qas:Label>
<qas:Line>S8 7BW</qas:Line>
</qas:AddressLine>
</qas:QAAddress>
</soap:Body>
</soap:Envelope>
Address searching
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.
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.
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.
Intuitive searching has elements of both Single Line 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.
Keyfinder searching works in a similar way to Single Line searching. The user types in the key reverse search term, and Pro Web returns the address that matches the search in the picklist.
SingleLine
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 is controlled through the Flatten engine option. This does not affect the way in which the initial search is performed, but does affect the number and type of picklist items that are returned.
Hierarchical 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:
- Users who are familiar with address capture process
- A responsive connection between the client and the integration.
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:
- Hierarchical picklist items which can be 'stepped into' to produce new picklists
- Picklist items that may contain 'informational' picklist items
- Picklists that will commonly contain fewer items than if the search was performed with the flattened mode, due to their hierarchical nature.
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
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:
- Auto-step flags (when these are returned, we suggest that the code performs a stepin action on the first picklist item)
- Auto-format flags (when these are returned, we suggest that the 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 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.
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.
Only certain special matches will require the refinement step.
This mode is designed to be used within an environment that has the following attributes:
- Users who are not familiar with address capture process
- An unresponsive connection between the client and integration (e.g. slow Internet connection)
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:
- Picklist items can't be refined (except for certain special cases)
- Picklists will not contain any 'informational' picklist items other than 'No Matches'
- Picklists returned using the flattened mode may contain more items than if the search was performed with the hierarchical mode. This is especially true if the search is not restricted using one of the recommended prompt sets
The flattened mode of the Single Line engine 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:
- Optimal
- Alternative
- Alternative 2 (USA only)
Auto Format
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
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
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 and Fuzzy Matching
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.
Hierarchical Mode
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:
- Users who are familiar with address capture process
- A responsive connection between the client and the integration.
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:
- Hierarchical picklist items which can be 'stepped into' to produce new picklists
- Picklist items that may contain 'informational' picklist items
- Picklists will update as the user enters more characters in the search field
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
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:
- Auto-step flags (when these are returned, we suggest that the code performs a
stepinaction on the first picklist item) - Auto-format flags (when these are returned, we suggest that the code performs a
formataction 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
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.
Using Verification
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:
- Verified as being correct
- Verified as being correct after user confirmation
- Not verified as being correct
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:
- Verified as being correct
- Verified as being correct after user confirmation
- Matched to one or more close addresses, which the user can interactively traverse
- Not verified
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.
VerifyLevels
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.
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.
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.
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'.
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.
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.
This verification level cannot be returned when using Primary Sourced datasets.
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.
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
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 are not supported by this engine.
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.
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, the uncaptured address will be classified and standardised.
There are certain types of picklist item that must be treated as special cases in Typedown and Single Line searches:
An unresolvable range is a picklist item that represents a range of premises, but where there is not enough information within the data to resolve the entry into a list of premises.
These are very common when searching against the USA data, although they also exist within other data and must be handled appropriately. For example, search using Single Line against the USA data using the optimal prompt set with the address:
Street Address: Arch St
Zip Code: 02110-14ND
This returns a page containing a text box that prompts the user to enter a premises value within the following range:
2...78 Arch St, Boston MA [even]
This is an unresolvable range, meaning that there is no available data to determine which possible even values between 2 and 78 are valid, and which are invalid. Therefore, the user has to specify the premises number that will resolve this picklist item, so that a single address can be generated from the range.
Phantom Primary Points (PPP) are specific to AUS address data.
A phantom primary point is a premises which is non-deliverable unless the user enters further secondary information. This secondary information may or may not be in the actual data. The user must enter this sub-premises information in order to complete a final address match. For example, search using Single Line against the AUS data using the optimal prompt set with the address:
Building number or PO Box: 44
Street: Miller St
Postcode: 2060
This returns a picklist where the first entry is:
44 Miller Street, NORTH SYDNEY NSW
This is marked as a PPP, which means that if this picklist item is selected, the integration must prompt the user for additional sub-premises information.
An incomplete address is an address that is not deliverable due to missing premises information within the data. This therefore requires the user to provide additional premises information so that the address is deliverable. For example, search using SingleLine against the DEU data using the optimal prompt set with the address:
Street: Feldburg
Building number or name:
Postcode: 50181
This returns a picklist with the following single entry:
Feldburg, BEDBURG 50181
This is marked as an incomplete address, which means that if this picklist item is selected, the integration must prompt the user for additional sub-premises information.
Dealing with Special Picklist Items
The following steps should be taken when a picklist item is flagged as an unresolvable range, Phantom Primary Point or an incomplete address:
1. The entry should be stepped into, in the same manner as with hierarchical picklists.
2. The premises information submitted by the user should then be used to refine the resulting picklist.
3. The picklist should contain a picklist item at the first position that does not have the original flag, but instead a FullAddress flag.
4. This flag can be used to format the address.
See xs:string PartialAddress and xs:boolean UnresolvableRange for details on these flags.
Keyfinder
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.
Flattened Mode
Picklist results for the Keyfinder engine are always returned in flattened mode:
The shaded boxes represent user actions; all other boxes are integration actions.
Some special matches will require a refinement step.
Searches performed using this mode will create a flattened picklist which may have one or more of the following properties:
- Picklist items can't be refined (except for certain special cases)
- Picklists will not contain any 'informational' picklist items other than 'No Matches'