Data Quality user documentation
home/Address validation/Pro Web/API reference (SOAP)/WSDL

WSDL

This section describes the WSDL document (proweb.wsdl) that is provided with this version of Pro Web.To access the WSDL document, ensure that the server is running and use the following URL:

http://server name:port name/proweb.wsdl

For example: http://localhost:2021/proweb.wsdl

The WSDL document is provided for integrators who want to communicate with the Pro Web Server, but do not want to base their integration on the standard integration code supplied with the product. Knowledge of the following technologies is assumed:

  • XML
  • XML Schema
  • SOAP
  • WSDL
  • HTTP

Supported Versions

SOAP

The server supports SOAP version 1.1 only.

HTTP

HTTP versions 1.1 and 1.0 are both supported.

Pro Web Server Operations

This section describes the Pro Web Server operations that make up the address capture and address verification processes.

Name Description
Can Search Check the combination of data mapping, engine, and layout are valid to search.
Initial Search Performs initial search.
Step In Steps into a picklist that was created during a previous search.
Refinement Refines a picklist that was created during a previous search.
Get Final Address Creates a final formatted address from a previously-created picklist item.

The capture of an address using the Verification engine, in the majority of cases, only needs to use the first, second, fourth and fifth operations.

Language Setting

Every input XML document has an optional language attribute which specifies the language in which the server will return errors and other messages to the user. The element is of the form:

qas:LanguageIDType Language

The table below lists the available languages and their language codes:

Language Code
English (American) 001
English (UK/AUS) 044
Dutch 031
French 033
Spanish 034
German 049

Search Process (Capture Of An Address)

Typically, the process of searching with the Singleline or Typedown engine follows the format outlined as follows:

  1. Pre-check - An optional check on the validity of a search against the intended engine/data mapping/layout combination. This uses the DoCanSearch action.

  2. Initial Search - This returns a Picklist object, which contains a list of PicklistItems that can be displayed. Each item can either be expanded, formatted into a final address or may be merely informational. The DoSearch action can be used for the initial search.

  3. Handling picklists and monikers - The picklist items are displayed to the user. Depending on the choice made by the user, one of the following will occur:

    • The DoRefine action can be used to step into a picklist result (for example, stepping into a street name will result in a picklist of premises). This hierarchical picklist behaviour is the default. If a single flattened picklist is required, the flatten flag must 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, refining with the text "high" on a picklist of street names will return another picklist containing only those streets starting with "high").
    • The DoRefine action is also called in certain special cases, for example where 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 PicklistItem returned by a previous call. These monikers encode the information required to recreate a particular picklist or picklist item, and are the means by which any integration navigates the search process.

  4. Format the final address.

Once a final address picklist item has been identified, the DoGetAddress action will apply a layout to the item, returning a FormattedAddress object that contains the final, formatted address.

Search Process (Verification)

The Verification engine is designed so that only minimal interaction, or none at all, is required from the user. This is the choice of the integrator. The user should enter their whole address in the same format the 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 a high enough 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 proceed in a similar fashion to the address capture process, 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 against the intended engine/data mapping/layout combination. This uses 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 the VerifyLevel. If picklists are not being handled, the integrator may simply check that the VerifyLevel is high enough before using the FormattedAddress.
  3. (Optional) - If required, you can handle the picklist using the DoRefine action.
  4. Format the final address - The DoGetAddress action will apply a layout to the item, returning a FormattedAddress object that contains the final, formatted address.

Server Operation Examples

The following examples describe in detail each of the Pro Web Server operations. Example SOAP communication is also provided.

An optional stage of the address capture process is to check that the combination of data mapping, engine and layout is valid for searching 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 a value of False if you specify a data mapping:

  • That is not installed
  • That cannot be found (for example, where an incorrect path has been specified)
  • That has expired
  • For which you do not have a valid license
  • For which the specified layout has not been defined (specifying a layout is optional)

It also returns a value of False if the meters 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, Singleline search engine and the layout named "( QAS Standard Layout )" being verified as valid.

Request:

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 456
SOAPAction: "http://www.qas.com/web-2013-12/DoCanSearch"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <web:QACanSearch xmlns:web="http://www.qas.com/web-2013-12">
            <web:Country>GBR</web:Country>
            <web:Engine Flatten="false"><a href="/address-validation/pro-web/next/address-search-types/singleline/" target="_self" title="">Singleline</a></web:Engine>
            <web:Layout>( QAS Standard Layout )</web:Layout>
        <web:/QACanSearch>
    </soapenv:Body>
</soapenv:Envelope>

Response:

HTTP/1.0 200 OK
Content-Length: 257
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QASearchOk xmlns:qas="http://www.qas.com/web-2013-12">
            <qas:IsOk>true</qas:IsOk>
        </qas:QASearchOk>
    </soap:Body>
</soap:Envelope>

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" to be searched against the GBR data mapping using the Singleline engine, and specifies the "(Standard Layout)" layout. The response is in the form of a Picklist item consisting of a single entry.

Request:

POST / HTTP/1.1
Content-Type: text/xml
Content-Length: 401
SOAPAction: "http://www.qas.com/web-2013-12/DoSearch"

<?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">
    <soap:Body>
        <web:QASearch xmlns:web="http://www.qas.com/web-2013-12">
            <web:Country>GBR</web:Country>
            <web:Engine Flatten="false"><a href="/address-validation/pro-web/next/address-search-types/singleline/" target="_self" title="">Singleline</a></web:Engine>
            <web:Layout>( QAS Standard Layout )</web:Layout>
            <web:Search>s87bw</web:Search>
        <web:/QASearch>
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Content-Length: 808
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QASearchResult xmlns:qas="http://www.qas.com/web-2013-12">
            <qas:QAPicklist AutoStepinSafe="true">
                <qas:Total>1</qas:Total>
                <qas:FullPicklistMoniker>3MGBREwPUBwMBAAEAARB5fYAA</qas:FullPicklistMoniker>
                <qas:Prompt>Enter selection</qas:Prompt>
                <qas:PicklistEntry Multiples="true" CanStep="true">
                    <qas:Picklist>Westwick Road, SHEFFIELD, S8 7BW</qas:Picklist>
                    <qas:PartialAddress>Westwick Road, SHEFFIELD S8 7BW</qas:PartialAddress>
                    <qas:Score>100</qas:Score>
                    <qas:Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:Moniker>
                </qas:PicklistEntry>
            </qas:QAPicklist>
        </qas:QASearchResult>
    </soap:Body>
</soap:Envelope>

If you want 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.

SOAP Action Input XML Document Output XML Document
/DoRefine QARefine QAPicklist

Description

Refines a picklist that was created during a previous search.

Example

The following example shows a refinement request using a moniker returned from the previous Initial Search example. The refinement request consists of the moniker of the street picklist item for "Westwick Road", and the refinement text is blank. The response is in the form of a picklist item containing 3 entries.

Request:

POST / HTTP/1.1
Content-Type: text/xml
Content-Length: 374
SOAPAction: "http://www.qas.com/web-2013-12/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">
    <soap:Body>
        <web:QARefine Threshold="50"
        xmlns:web="http://www.qas.com/web-2013-12">
            <web:Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</web:Moniker>
        <web:Refinement />
        <web:/QARefine>
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Content-Length: 1339
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QAPicklist xmlns:qas="http://www.qas.com/web-2013-12">
            <qas:Total>3</qas:Total>
            <qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker>
            <qas:Prompt>Enter building number/name or organization</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>

If you want to refine a picklist, you should use the SOAP action DoRefine 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 previous search.

Example

Continuing from the previous 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.1
Content-Type: text/xml
Content-Length: 388
SOAPAction: "http://www.qas.com/web-2013-12/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">
    <soap:Body>
        <web:QARefine Threshold="50"
        xmlns:web="http://www.qas.com/web-2013-12">
            <web:Moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</web:Moniker>
            <web:Refinement>205</web:Refinement>
        <web:/QARefine>
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Content-Length: 705
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QAPicklist xmlns:qas="http://www.qas.com/web-2013-12">
            <qas:Total>1</qas:Total>
            <qas:FullPicklistMoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:FullPicklistMoniker>
            <qas:Prompt>Enter building number/name or organization</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>

The final stage of the address capture process is to obtain a final address using the DoGetAddress action. The picklist item SPM of the PicklistEntry that you want to format should be passed in as input.

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 previous Refinement example, the moniker of the single picklist entry for "205 Westwick Road" is passed along with the "( Standard Layout)" Layout. The response contains the captured address, formatted according to the specified layout.

Request:

POST / HTTP/1.1
Content-Type: text/xml
Content-Length: 383
SOAPAction: "http://www.qas.com/web-2013-12/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">
    <soap:Body>
        <web:QAGetAddress xmlns:web="http://www.qas.com/web-2013-12">
            <web:Moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</web:Moniker>
            <web:Layout>( QAS Standard Layout )</web:Layout>
        <web:/QAGetAddress>
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Content-Length: 927
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QAAddress xmlns:qas="http://www.qas.com/web-2013-12">
            <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>

The bulk search process performs address Verification on one or more addresses. Unlike the normal search process, the bulk search process consists of a single step: each address is either verified and returns a formatted address, or is not verified.

SOAP Action Input XML Document Output XML Document
/DoBulkSearch QABulkSearch QABulkSearchResult

Description

Carries out a bulk Verification search.

Example

This example shows two addresses being verified against the USA data mapping.

Request:

POST / HTTP/1.1
SOAPAction: "http://www.qas.com/web-2013-02/DoBulkSearch"
Content-Type: text/xml
Content-Length: 614
Proxy-Connection: Keep-Alive
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QABulkSearch xmlns:qas="http://www.qas.com/web-2013-12">
            <qas:Country>USA</qas:Country>
            <qas:Layout>( QAS Standard Layout )</qas:Layout>
            <qas:Engine Flatten="false" Threshold="50"
            Timeout="20000" PromptSet="Default"
            Intensity="Close">Verification</qas:Engine>
            <qas:BulkSearchTerm>
                <qas:Search>555 Ellis St| Mountain View| CA| 94043</qas:Search>
                <qas:Search>222 Charles St| Cambridge| MA| 01241</qas:Search>
            </qas:BulkSearchTerm>
        </qas:QABulkSearch>
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Content-Length: 2899
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <qas:QABulkSearchResult xmlns:qas="http://www.qas.com/web-
        2013-12" Count="2" SearchCount="4">
            <qas:BulkAddress VerifyLevel="Verified">
                <qas:QAAddress>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line>555 Ellis St</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line></qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line></qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>City name</qas:Label>
                        <qas:Line>Mountain View</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>State code</qas:Label>
                        <qas:Line>CA</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label></qas:Label>
                        <qas:Line>94043-2214</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>Country</qas:Label>
                        <qas:Line>UNITED STATES OF AMERICA</qas:Line>
                    </qas:AddressLine>
                </qas:QAAddress>
                <qas:InputAddress>555 Ellis St| Mountain View| CA| 94043</qas:InputAddress>
            </qas:BulkAddress>
            <qas:BulkAddress VerifyLevel="Verified">
                <qas:QAAddress>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line>222 Charles St</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line></qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="None">
                        <qas:Label></qas:Label>
                        <qas:Line></qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>City name</qas:Label>
                        <qas:Line>Cambridge</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>State code</qas:Label>
                        <qas:Line>MA</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label></qas:Label>
                        <qas:Line>02141-2004</qas:Line>
                    </qas:AddressLine>
                    <qas:AddressLine LineContent="Address">
                        <qas:Label>Country</qas:Label>
                        <qas:Line>UNITED STATES OF AMERICA</qas:Line>
                    </qas:AddressLine>
                </qas:QAAddress>
                <qas:InputAddress>222 Charles St| Cambridge| MA| 01241</qas:InputAddress>
            </qas:BulkAddress>
        </qas:QABulkSearchResult>
    </soap:Body>
</soap:Envelope>
Pro Web

API reference (SOAP)