Monikers and IDs
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.
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. |
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:
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. |
Defines a 3 character data identifier. This is the country's ISO code in most cases. The available data mappings can be accessed using the SOAP action DoGetData. Please find below a list of special data identifiers combining multiple UK datasets.
| Data identifier | Description |
|---|---|
| GBR | United Kingdom |
| MRF | United Kingdom with Multiple Residence |
| GBB | United Kingdom with Business |
| GBE | United Kingdom with Electricity |
| GBG | United Kingdom with Gas |
| GBN | United Kingdom with Names |
| GBX | United Kingdom with Extended Business |
| GX0 | United Kingdom with Not Yet Built |
| GX1 | United Kingdom with Names and Not Yet Built |
| GX2 | United Kingdom with Names and Business |
| GX3 | United Kingdom with Names, Business and Not Yet Built |
| GX4 | United Kingdom with Business and Not Yet Built |
| GX5 | United Kingdom with Electricity and Gas |
| GX6 | United Kingdom with Multiple Residence, Business and Not Yet Built |
| GX7 | United Kingdom with Names and Multiple Residence |
| GX8 | United Kingdom with Not Yet Built and Multiple Residence |
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 100 items. Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches. Intuitive specific behavior:
|
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 SingleLine 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. |
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.
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 100 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. Picklists resulting from searches against Partner Sourced datasets will return up to 20 matches. 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 step-in 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. |
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.
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. |
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.
There is no XML document that needs to be passed for this SOAP action.
Obtains information about the server.
This action is performed to access a list of system information text which may be useful to integrators.
There is no XML document that needs to be passed for this SOAP action.
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.
Partner Sourced datasets
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. |
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.
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. |
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:
While the alternate prompt set for USA has four input lines:
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 Engine |
This specifies the engine type to be used to perform the subsequent search. |
