Data Quality user documentation
home/Address validation/Address Validate SOAP/API reference/SOAP requests

SOAP requests

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.

DoCanSearch 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.

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.

DoSearch 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:
  • Singleline uses the SingleLine engine to perform the search.
  • Typedown uses the Typedown engine to perform the search.
  • Verification uses the Verification engine to perform the search.
  • Intuitive uses the Intuitive engine to perform the search.
  • Keyfinder uses the Keyfinder engine to perform the search.
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:
  • This defines the maximum picklist size which is returned by the intuitive search engine.
  • This element is always relevant when used with the intuitive engine.
  • It defaults to the value set for the IntuitiveSearchMaxPicklist configuration but will override that configuration if provided.
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:
  • Exact. This does not allow many mistakes in the search term, but is the fastest.
  • Close. This allows some mistakes in the search term, and is the default setting.
  • Extensive. This allows many mistakes in the search term, and will take the longest.
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.

DoRefine 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 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.

DoGetAddress Request

Input XML Document: QAGetAddress

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.

DoGetData Request

Input XML Document: None

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.

DoGetSystemInfo Request

Input XML Document: None

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.

DoGetExampleAddresses 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.

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.

DoGetLayouts 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.

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

DoGetPromptSet 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:
  • OneLine. All search text to be submitted upon a single line.
  • Default. the default prompt set for the engine.
  • Generic. A general data-independent prompt set.
  • Optimal. Requires the minimum possible amount of search text to perform a search.
  • Alternate. An extended country-specific set for where the information required for an optimal search is not available.
  • Alternate2. A different alternative prompt set (USA only).
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.
Address Validate SOAP

API reference