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.
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. |
xs:string 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. |
xs:string 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. |
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 returns a QASearchResult document, which defines the result of the search process. The verification engine will return results in a different manner to the SingleLine 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.This contains information about a picklist of results. Picklists are returned when searching with the Typedown and SingleLine engines, and may be returned from the Verification and Keyfinder engines. |
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.The Verification engine will return one of a set of VerifyLevels for a search, each of which may be treated differently by the integrator depending upon the amount of user interaction that is required. |
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. |
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. |
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:
A search result is formatted using the layout that was specified in the Layout element of the QASearchdocument. When searching using the SingleLine 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 sub-premises information. This is currently only relevant when using Canada data. |
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:
|
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 picklist type defines a set of result items and properties that are returned from a step-in 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. |
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 non-informational 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 non-informational 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. |
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 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 attribute indicates that the address is a large volume receiver and may be missing sub-premises information. This is currently only relevant when using Canada data. |
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. |
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>
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.
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. |
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. |
Obtains information about the server.
This action is performed to access a list of system information text which may be useful to integrators.
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. |
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
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. |
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". |
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:
|
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:
|
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.
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. |
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. |
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:
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. |
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". |