Data Quality user documentation | Server operation examples

Each Address Validate SOAP API request requires username and password or the token to be submitted as part of the communication. Examples below use a sample username and password.

For examples with token authentication please refer to our sample code for C# and PHP.

An optional stage of the address search process is to check that the combination of data mapping, engine and layout is valid by using the DoCanSearch action.

Metered datasets

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

CanSearch description

Returns False if you specify a data mapping:

That is not supported
For which you do not have a valid license
For which the specified layout has not been defined (spsecifying a layout is optional)

It also returns False if the credits have run out, or if the requested engine is not appropriate or available (for example, verification is only available for some data mappings).

The operation also returns information as to why a value of False was returned.

CanSearch example

The following example shows the combination of the GBR data mapping, SingleLine engine and the layout "QADefault" being verified as valid.

CanSearch request

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
   <soapenv:header>
      <ond:qaqueryheader>
         <ond:qaauthentication>
            <ond:username></ond:username>
            <ond:password></ond:password>
         </ond:qaauthentication>
         <ond:security>
            <!--You may enter ANY elements at this point-->
         </ond:security>
      </ond:qaqueryheader>
   </soapenv:header>
   <soapenv:body>
      <ond:qacansearch>
         <ond:country>GBR</ond:country>
         <ond:engine>Singleline</ond:engine>
         <!--Optional:-->
         <ond:layout>QADefault</ond:layout>
      </ond:qacansearch>
   </soapenv:body>
</soapenv:envelope>

CanSearch response

<?xml version="1.0" encoding="UTF-8"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:header>
      <qainformation xmlns="http://www.qas.com/OnDemand-2011-03">
         <statetransition>Unknown</statetransition>
         <creditsused>0</creditsused>
      </qainformation>
   </soap:header>
   <soap:body>
      <qasearchok xmlns="http://www.qas.com/OnDemand-2011-03">
         <isok>true</isok>
      </qasearchok>
   </soap:body>
</soap:envelope>

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

Initial Search 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.

DoSearch

Sending a layout for DoSearch is optional but recommended for verification searches where a final address can be returned.

Initial Search example

The following example submits the search string "s87bw" against the GBR data using the SingleLine engine, and specifies the "( QAS Standard Layout )" layout. The response is in the form of a picklist item consisting of a single entry.

Initial Search request

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ond="http://www.qas.com/OnDemand-2011-03">
   <soapenv:header>
      <ond:qaqueryheader>
         <ond:qaauthentication>
            <ond:username></ond:username>
            <ond:password></ond:password>
         </ond:qaauthentication>
         <ond:security>
            <!--You may enter ANY elements at this point-->
         </ond:security>
      </ond:qaqueryheader>
   </soapenv:header>
   <soapenv:body>
      <ond:qasearch>
         <ond:country>USA</ond:country>
         <ond:engine>Singleline</ond:engine>
         <!--Optional:-->
         <ond:layout>QADefault</ond:layout>
         <ond:search>1 alpine ave,10301</ond:search>
         <!--Optional:-->
         <ond:formattedaddressinpicklist>false</ond:formattedaddressinpicklist>
      </ond:qasearch>
   </soapenv:body>
</soapenv:envelope>

Initial Search response

<?xml version="1.0" encoding="UTF-8"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:header>
      <qainformation xmlns="http://www.qas.com/OnDemand-2011-03">
         <statetransition>PickList</statetransition>
         <creditsused>0</creditsused>
      </qainformation>
   </soap:header>
   <soap:body>
      <qasearchresult xmlns="http://www.qas.com/OnDemand-2011-03">
         <qapicklist autoformatsafe="true">
            <fullpicklistmoniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|6MUSADwvfBwEBAQABAAWcHJ4AAAAAADEAZA--</fullpicklistmoniker>
            <picklistentry fulladdress="true">
               <moniker>USA|524b8f58-12d9-4103-b762-6a0ff017df48|vOUSADwvfBwEDAQAFnByeAAAAAAAxAGQA</moniker>
               <partialaddress>1 Alpine Ave, Staten Island NY 10301-4001</partialaddress>
               <picklist>1 Alpine Ave, Staten Island NY</picklist>
               <postcode>10301-4001</postcode>
               <score>100</score>
            </picklistentry>
            <prompt>Enter selection</prompt>
            <total>1</total>
         </qapicklist>
         <verificationflags>
            <postcodecorrected>true</postcodecorrected>
         </verificationflags>
      </qasearchresult>
   </soap:body>
</soap:envelope>

If you want to 'step into' a picklist result, you should use the DoRefine action with the picklist item SPM (Search Point Moniker - used to store the state of a search that is in progress; each picklist item has a SPM) contained within a PicklistEntryType structure and a blank refinement string.

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

'Step In' description

Refines a picklist that was created during a search.

'Step In' example

The following example shows a refinement request using a moniker (name used to uniquely identify each object) returned from the initial search example. The refinement request consists of the street picklist item for "Westwick Road" moniker and the refinement text is blank. The response is in the form of a picklist item containing 3 entries.

'Step In' request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 374
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"

<?xml version="1.0"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soapenv:header>
    <ond:qaauthentication>
      <ond:username>572c3-8b4</ond:username>
      <ond:password>YourPassw0rd</ond:password>
    </ond:qaauthentication>
  </soapenv:header>
  <soap:body>
    <qarefine threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01">
      <moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</moniker>
      <refinement></refinement>
    </qarefine>
  </soap:body>
</soap:envelope>

'Step In' response

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

<?xml version="1.0" encoding="UTF-8"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:header>
      <qainformation xmlns="http://www.qas.com/OnDemand-2010-01">
         <creditsused>1</creditsused>
      </qainformation>
   </soap:header>
   <soap:body>
      <qas:qapicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01">
         <qas:total>3</qas:total>
         <qas:fullpicklistmoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:fullpicklistmoniker>
         <qas:prompt>Enter building number/name or organisation</qas:prompt>
         <qas:picklistentry multiples="true" canstep="true">
            <qas:picklist>121 ... 161 [odd]</qas:picklist>
            <qas:partialaddress>Westwick Road, SHEFFIELD, S8 7BW</qas:partialaddress>
            <qas:score>0</qas:score>
            <qas:moniker>dOGBREwPUBwMBAAEQeX_AAAA-</qas:moniker>
         </qas:picklistentry>
         <qas:picklistentry fulladdress="true">
            <qas:picklist>161a</qas:picklist>
            <qas:partialaddress>161a Westwick Road,SHEFFIELD, S8 7BW</qas:partialaddress>
            <qas:score>0</qas:score>
            <qas:moniker>0OGBREwPUBwMBAAEQeYYAAAA-</qas:moniker>
         </qas:picklistentry>
         <qas:picklistentry multiples="true" canstep="true">
            <qas:picklist>163 ... 207 [odd]</qas:picklist>
            <qas:partialaddress>Westwick Road, SHEFFIELD, S8 7BW</qas:partialaddress>
            <qas:score>0</qas:score>
            <qas:moniker>HOGBREwPUBwMBAAEQeYdAAAA-</qas:moniker>
         </qas:picklistentry>
      </qas:qapicklist>
   </soap:body>
</soap:envelope>

If you want to refine a picklist, you should use the DoRefine action with the full picklist moniker contained within a picklist structure and a non-blank refinement string.

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

Refine description

Refines a picklist that was created during a search.

Refine example

Continuing from the above 'step in' example, the user has entered refinement text of "205". In this case, the refinement request uses the moniker of the full picklist from the previous operation and the refinement text "205" in the refinement field. The response is a picklist item containing a single entry.

Refine request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 388
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoRefine"

<?xml version="1.0"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soapenv:header>
    <ond:qaauthentication>
      <ond:username>572c3-8b4</ond:username>
      <ond:password>YourPassw0rd</ond:password>
    </ond:qaauthentication>
  </soapenv:header>
  <soap:body>
    <qarefine threshold="50" xmlns="http://www.qas.com/OnDemand-2010-01">
      <moniker>ZOGBREwPUBwMBAAEQeX2AAAA-</moniker>
      <refinement>205</refinement>
    </qarefine>
  </soap:body>
</soap:envelope>

Refine response

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

<?xml version="1.0"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:header>
    <qainformation xmlns="http://www.qas.com/OnDemand-2010-01">
      <creditsused>1</creditsused>
    </qainformation>
  </soap:header>
  <soap:body>
    <qas:qapicklist xmlns:qas="http://www.qas.com/OnDemand-2010-01">
      <qas:total>1</qas:total>
      <qas:fullpicklistmoniker>ZOGBREwPUBwMBAAEQeX2AAAA-</qas:fullpicklistmoniker>
      <qas:prompt>Enter building number/name or organisation</qas:prompt>
      <qas:picklistentry fulladdress="true">
        <qas:picklist>205</qas:picklist>
        <qas:partialaddress>205 Westwick Road,SHEFFIELD, S8 7BW</qas:partialaddress>
        <qas:score>0</qas:score>
        <qas:moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</qas:moniker>
      </qas:picklistentry>
    </qas:qapicklist>
  </soap:body>
</soap:envelope>

The last stage is to obtain the final address using the DoGetAddress action. As input, the picklist item SPM of the PicklistEntry that you want to format should be passed.

SOAP Action	Input XML Document	Output XML Document
/DoGetAddress	QAGetAddress	QAAddress

Get Final Address description

Creates a final, formatted address from a previously-created picklist item.

Get Final Address example

Continuing from the above refine example, the moniker of the single picklist entry for "205 Westwick Road" is passed along with the "QADefault" layout. The response contains the address formatted according to the specified layout.

Get Final Address request

POST / HTTP/1.0
Content-Type: text/xml
Content-Length: 383
SOAPAction: "http://www.qas.com/OnDemand-2010-01/DoGetAddress"

<?xml version="1.0"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soapenv:header>
    <ond:qaauthentication>
      <ond:username>572c3-8b4</ond:username>
      <ond:password>YourPassw0rd</ond:password>
    </ond:qaauthentication>
  </soapenv:header>
  <soap:body>
    <qagetaddress xmlns="http://www.qas.com/OnDemand-2010-01">
      <moniker>JOGBREwPUBwMBAAEQeYdAMjA1AAA-</moniker>
      <layout>QADefault</layout>
    </qagetaddress>
  </soap:body>
</soap:envelope>

Get Final Address response

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

<?xml version="1.0"?>
<soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:header>
    <qainformation xmlns="http://www.qas.com/OnDemand-2010-01">
      <creditsused>1</creditsused>
    </qainformation>
  </soap:header>
  <soap:body>
    <qas:qaaddress xmlns:qas="http://www.qas.com/OnDemand-2010-01">
      <qas:addressline linecontent="None">
        <qas:label></qas:label>
        <qas:line>205 Westwick Road</qas:line>
      </qas:addressline>
      <qas:addressline linecontent="None">
        <qas:label></qas:label>
        <qas:line></qas:line>
      </qas:addressline>
      <qas:addressline linecontent="Address">
        <qas:label>Town</qas:label>
        <qas:line>SHEFFIELD</qas:line>
      </qas:addressline>
      <qas:addressline linecontent="Address">
        <qas:label>County</qas:label>
        <qas:line></qas:line>
      </qas:addressline>
      <qas:addressline linecontent="Address">
        <qas:label>Postcode</qas:label>
        <qas:line>S8 7BW</qas:line>
      </qas:addressline>
    </qas:qaaddress>
  </soap:body>
</soap:envelope>

Was this helpful?

Previous: SOAP responses

Next: Rate limiting

Address Validate SOAP

API reference

Next topic:
FAQs
Previous topic:
Prerequisites