• To use this functionality you will need to buy an Address Lookup click bundle from the Shop located in our Portal. Register for the Portal here.
• Authentication, per service request, is via an http / https header using the Address Lookup user token credentials.
• The interface definition (WSDL) can be downloaded from the service here. This can be used in a SOAPUI project in assessing service capability. Please see ‘SOAP API Introduction’ section within Basics for further details.
• Addresses are usually sought using either Postcode (ZipCode) or other address elements (which may include a Postcode). Postcode Lookup Walkthrough and / or Address Search Walkthrough sections will guide you through this using VB.NET samples complete with documentation provided in each case.
• Other address search methods can be used in addition or in preference to the above. Which ones will depend upon the ‘extra data’ included in the reference files drawn upon by the click bundle in play. See the following Address search from a given… sections in Customisations…
  • Index
  • Personal Name*
  • Grid Reference
• Searches submitted must draw upon a Master Address File (MAF) bundle included in the service account (see ‘How do I discover my available Master Address Files?’ again within Basics).
• Customise an address label, and obtain extra data (see Customisations section).

Authentication

Authentication is based on the WS-Security UsernameToken, where the default password type (PasswordText) is applied. Each request must be authenticated via a token name and password combination, which is supplied in the SOAP header. To secure this information all requests should use the https:// protocol, in preference to http://.

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <soapenv:Header>
    <wss:Security>
      <wss:UsernameToken>
        <wss:Username>hpwuser</wss:Username>
        <wss:Password>password</wss:Password>
      </wss:UsernameToken>
    </wss:Security>
  </soapenv:Header>
  <soapenv:Body>
    ... etc ...
  </soapenv:Body>
</soapenv:Envelope>

NOTE: Subsequent examples within the documentation will only display the SOAP message Body as the Envelope and Header (shown above) are common to all requests.

SOAP API Introduction

This introduction will use SoapUI in demonstrating capability when using the SOAP API. SOAP can be easily integrated into a wide range of languages.

You can download SoapUI free of charge from www.soapui.org. This introduction does not use any features of the Pro version.

Start a new project from the menu or toolbar, give the project a name and enter the WSDL:
https://cloud.hopewiser.com/soapaddrsvr/soapaddrsvr.wsdl

 

Expand the Status node in the project navigator and double-click on Request 1.

In the template request, replace the ? placeholders with the token name and password you created during registering for Address Lookup.

Click the green run arrow and you should see the response from the server.

During initial registration you were provided with some free clicks against the UK Postal Address File. The MAF tag within the response body contains the reference for this plan (uk-rm-paf), which will be used in subsequent requests. Additional MAF tags will be shown if you purchase different plans. You can also see the available plans within Your Account.

To perform a simple postcode lookup, expand the PostcodeLookup node in the project navigator and double-click on Request 1. Replace the ? placeholders for the Username, Password, Postcode (Premise too in refining the Postcode search results if you wish) and MAF. Remove all other options.

Click the green run arrow and you will see the response from the server.

This “Quickstart” has demonstrated the interface to obtain user status information and perform a basic postcode lookup.

A partial address lookup would feature the use of the AddressSearch SOAP API function with responses from this (each referencing a SID) expanded as required using the AddressExpand function.

Again, the Address Search Walkthrough will fully demonstrate the partial address lookup mechanics.

How do I discover my available Master Address Files?

The Status function is used to obtain the user configuration, identifying your default Master Address File (MAF) and a list of possible alternate MAFs.

A Status request does not require any parameters.

<soapenv:Body>
  <hpw:StatusRequest/>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes). Successful responses will also identify the user’s provisioned MAFs. This may include a default MAF and a list of possible alternate MAFs.

Each MAF has attributes to specify its version and (optionally) a blocked reason. The presence of a blockedReason attribute indicates that access to that MAF has been disabled. Its value provides a textual description of the blocking reason, for example “No credit remaining”.

<soapenv:Body>
  <hpw:StatusResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Default>
      <hpw:MAF version="MAF Version 58 (UU)  UNITED KINGDOM  Built 20140408">
        uk-rm-paf
      </hpw:MAF>
    </hpw:Default>
    <hpw:Alternate>
      <hpw:MAF version="MAF Version 58 (UU)  UNITED KINGDOM  Built 20140408 GRID">
        uk-nspd-paf
      </hpw:MAF>
    </hpw:Alternate>
  </hpw:StatusResponse>
</soapenv:Body>

How do I customise an address label?

<soapenv:Body>
  <hpw:AddressDetailsRequest>
    <hpw:SID>
      %+2+0%DOWNING STREET||LONDONi8%uk-rm-paf%single_step%250
      %EnglishOnly%yes%no%no
    </hpw:SID>
    <hpw:RequestOptions>
      <hpw:AddressType>formatted_label</hpw:AddressType>
    </hpw:RequestOptions>
    <hpw:FormattedLabelOptions>
      <hpw:LabelFormat>fixed_postcode</hpw:LabelFormat>
      <hpw:CaseFormat>upper</hpw:CaseFormat>
      <hpw:DropNameFromLabel>yes</hpw:DropNameFromLabel>
    </hpw:FormattedLabelOptions>
  </hpw:AddressDetailsRequest>
</soapenv:Body>

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:FormattedLabel status="ok">
        <hpw:Line1>PRIME MINISTER & FIRST LORD OF THE TREASURY</hpw:Line1>
        <hpw:Line2>10 DOWNING STREET</hpw:Line2>
        <hpw:Line3>LONDON</hpw:Line3>
        <hpw:Line4/>
        <hpw:Line5/>
        <hpw:Line6>SW1A 2AA</hpw:Line6>
      </hpw:FormattedLabel>
    </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

How do I obtain individual address or common data fields?

The SOAP Address Service supports the address and common data fields found in the Common Output Fields section, which are available from all Master Address Files (MAFs).

To obtain one of more of these fields add a Data tag to your request that specifies the name of each required item.

Here is an example AddressDetails request – requesting both the Country and Delivery Point fields.

<soapenv:Body>
    <hpw:AddressDetailsRequest>
      <hpw:SID>
        %+2+0%DOWNING STREET||LONDONi8%uk-rm-paf%single_step%250
        %EnglishOnly%yes%no%no
      </hpw:SID>
      <hpw:Data>
        <hpw:Item>country</hpw:Item>
        <hpw:Item>dp</hpw:Item>
      </hpw:Data>
    </hpw:AddressDetailsRequest>
  </soapenv:Body>
</soapenv:Envelope>

Please note that each requested data item will be returned in the SOAP Address Service response, even if it does not contain a value.

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
     <hpw:StatusCode>0</hpw:StatusCode>
     <hpw:StatusDesc>Successful</hpw:StatusDesc>
     <hpw:Match number="1">
        <hpw:Address>
           <hpw:Organisation>
             Prime Minister & First Lord of The Treasury
           </hpw:Organisation>
           <hpw:Line1>10 Downing Street</hpw:Line1>
           <hpw:Town>LONDON</hpw:Town>
           <hpw:Postcode>SW1A 2AA</hpw:Postcode>
           <hpw:DP>1AM</hpw:DP>
        </hpw:Address>
        <hpw:Data>
           <hpw:Item name="country">UNITED KINGDOM</hpw:Item>
           <hpw:Item name="dp">1AM</hpw:Item>
        </hpw:Data>
     </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

How do I obtain additional (‘extra’) data items?

The ExtraData function is used to obtain a list of extra data items that can be returned from a specific Master Address File (MAF). These are items in addition to those common to all MAFs. For example National Statistics Postcode Directory (NSPD) data.

An ExtraData request may take an optional MAF parameter to identify the required MAF. If omitted the user’s default MAF will be applied.

An example ExtraData request for a MAF containing NSPD data would be.

<soapenv:Body>
    <hpw:ExtraDataRequest>
      <hpw:MAF>uk-nspd-paf</hpw:MAF>
    </hpw:ExtraDataRequest>
  </soapenv:Body>
</soapenv:Envelope>

The response will always contain a status code and description (see Status Codes). Please note that status code 4 will be returned if the specified MAF does not contain any extra data items.

Successful responses will also contain a list of available extra data items.

<soapenv:Body>
  <hpw:ExtraDataResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:ExtraData>
      <hpw:Item>ORGANISATION KEY</hpw:Item>
      <hpw:Item>ADDRESS KEY</hpw:Item>
      <hpw:Item>Grid Postcode</hpw:Item>
      <hpw:Item>Grid X</hpw:Item>
      <hpw:Item>Grid Y</hpw:Item>
      ... etc ...
    </hpw:ExtraData>
  </hpw:ExtraDataResponse>
</soapenv:Body>

To obtain these extra data fields add an ExtraData tag to your request that specifies the name of each required item.

Below is an example AddressDetails request – requesting the grid reference fields.

<soapenv:Body>
  <hpw:AddressDetailsRequest>
    <hpw:SID>
      %+2+0%DOWNING STREET||LONDONi8%uk-nspd-paf%single_step%250
      %EnglishOnly%yes%no%no
    </hpw:SID>
    <hpw:ExtraData>
      <hpw:Item>Grid X</hpw:Item>
      <hpw:Item>Grid Y</hpw:Item>
    </hpw:ExtraData>
  </hpw:AddressDetailsRequest>
</soapenv:Body>

It is possible for multiple values to exist per extra data item. Hence, the requested items are grouped into records, where the first set of item values comprise the first record, the second set comprise the next record, etc. SOAP Address Service responses will only contain extra data records when at least one item has a value. However, if a record is present then it will contain each requested data item, some of which may have an empty value.

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
     <hpw:StatusCode>0</hpw:StatusCode>
     <hpw:StatusDesc>Successful</hpw:StatusDesc>
     <hpw:Match number="1">
        <hpw:Address>
           <hpw:Organisation>
             Prime Minister & First Lord of The Treasury
           </hpw:Organisation>
           <hpw:Line1>10 Downing Street</hpw:Line1>
           <hpw:Town>LONDON</hpw:Town>
           <hpw:Postcode>SW1A 2AA</hpw:Postcode>
           <hpw:DP>1AM</hpw:DP>
        </hpw:Address>
        <hpw:ExtraDataRecord number="1">
           <hpw:Item name="Grid X">0530047</hpw:Item>
           <hpw:Item name="Grid Y">0179951</hpw:Item>
      </hpw:ExtraDataRecord>
    </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

How do I obtain an address from a given index?

<soapenv:Body>
  <hpw:AddressSearchByIndexRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:Index>ORGANISATION</hpw:Index>
    <hpw:Value>Hopewiser Ltd</hpw:Value>
  </hpw:AddressSearchByIndexRequest>
</soapenv:Body>

<soapenv:Body>
  <hpw:AddressSearchByIndexResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:SID>
        %+0%@ORGANISATION@HOPEWISER LTD0p%uk-rm-paf%single_step%250
        %EnglishAndWelsh%yes%no%no
      </hpw:SID>
      <hpw:Text>Hopewiser Ltd,Merlin Court,Atlantic Street,
                Altrincham,Cheshire</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
  </hpw:AddressSearchByIndexResponse>
</soapenv:Body>

<soapenv:Body>
  <hpw:AddressExpandRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%@ORGANISATION@HOPEWISER LTD0p%uk-rm-paf%single_step%250
      %EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressExpandRequest>
</soapenv:Body>

<soapenv:Body>
<hpw:AddressExpandResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
  <hpw:StatusCode>5</hpw:StatusCode>
  <hpw:StatusDesc>Item cannot be expanded</hpw:StatusDesc>
  </hpw:AddressExpandResponse>
</soapenv:Body>

<soapenv:Body>
  <hpw:AddressDetailsRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%@ORGANISATION@HOPEWISER LTD0p%uk-rm-paf%single_step%250
      %EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressDetailsRequest>
</soapenv:Body>

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:Address>
        <hpw:Organisation>Hopewiser Ltd</hpw:Organisation>
        <hpw:Line1>Merlin Court</hpw:Line1>
        <hpw:Line2>Atlantic Street</hpw:Line2>
        <hpw:Town>ALTRINCHAM</hpw:Town>
        <hpw:County>Cheshire</hpw:County>        
        <hpw:Postcode>WA14 5NL</hpw:Postcode>
        <hpw:DP>1HQ</hpw:DP>
      </hpw:Address>
    </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

*Address search from a given personal name*

The AddressSearchByName* function is used to drill down a hierarchy of matched items to locate a specific address and obtain its details. The initial search criteria can be a forename* and/or surname* plus an optional address filter. The address can be returned in a default format or can be customised into a formatted label. Individual address elements and additional data items may also be returned.

The actual search and recovery of matched detail is achieved via three separate requests; AddressSearchByName*, AddressExpand and AddressDetails.

1. The AddressSearchByName request initiates the search, for the given search criteria plus request options, and returns a list of matched items.
2. The AddressExpand request continues the search, by expanding a specific matched item, and returns a new list of matched items at the next search level. This is repeated until no further expansion is possible.
3. The AddressDetails request obtains the address and associated data for a specific matched item.

NOTE: The AddressSearchByName* function is only available when the Master Address File contains appropriate data. For further details please refer to the How do I discover the searching capability of a given MAF? below.

AddressSearchByName request*

The AddressSearchByName request* consists of three core parameters; the Forename*, Surname* and optional AddressFilter (Input1..Input10).

• • If the requested MAF only supports surname* searching, then the Surname* is mandatory.

• • If the requested MAF supports both Forename* and Surname* searching, then either Forename* and/or Surname* parameter must be specified.

• The AddressFilter is optional, but would generally be provided to narrow the search to a specific area. This could be a postcode, a full or partial address. Splitting address elements (e.g. premise name, street, town, etc.) into separate input lines generally yields better results.

NOTE: The maximum number of supported search criteria inputs is 10. This means that only 10 items from the Forename*, Surname* and AddressFilter (Input1..Input10) should be given a value.

All other parameters are optional and should only be supplied when a non-default configuration is required.

Below is an example AddressSearchByName* request for a fictitious person, “Joe Bloggs” in “Altrincham”.

<soapenv:Body>
  <hpw:AddressSearchByNameRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:Forename>Joe</hpw:Forename>
    <hpw:Surname>Bloggs</hpw:Surname>
    <hpw:Input1>Altrincham</hpw:Input1>
  </hpw:AddressSearchByNameRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below). Please note if a search does not fully complete (i.e. find all possible matches), then the entire request will be treated as a failure and an appropriate status code/description will be returned (e.g. “Too many matches”).

Successful responses will also contain one or more matched items. Each matched item will contain a number attribute (a simple count) and the elements listed below.

Below is an example AddressSearchByName* response for “Joe Bloggs” in “Altrincham”.

<soapenv:Body>
  <hpw:AddressSearchByNameResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:SID>
        %+0%JOE@1||BLOGGS@2||ALTRINCHAMmx%uk-test-nc-extract-current
        %single_step%250%EnglishAndWelsh%yes%no%no
      </hpw:SID>
      <hpw:Text>Hopewiser Ltd,Merlin Court,Atlantic Street,
                Altrincham,Cheshire [Mr Joe Bloggs]</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
  </hpw:AddressSearchByNameResponse>
</soapenv:Body>

AddressExpand request

The AddressExpand request continues a search, by expanding a specific matched item, and returns a new list of matched items at the next search level. This should be repeated until no further expansion is possible.

Matched items with either the Expandable flag value yes or the ExpandableToName* flag value yes can be expanded.

It only requires the SID (Search IDentity) of the matched item to be expanded. This will have been obtained from either the initial search request or a preceding AddressExpand request.

All other parameters are optional and should only be supplied when a non-default configuration is required.

Below is an example AddressExpanded request – continuing the search for “Joe Bloggs” in “Altrincham”.

<soapenv:Body>
  <hpw:AddressExpandRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%JOE@1||BLOGGS@2||ALTRINCHAMmx%uk-test-nc-extract-current
      %EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressExpandRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below). Please note if a search does not fully complete (i.e. find all possible matches), then the entire request will be treated as a failure and an appropriate status code/description will be returned (e.g. “Too many matches”).

Successful responses will also contain one or more matched items. Each matched item will contain a number attribute (a simple count) and the elements listed below.

Below is an example AddressExpand response – continuing the search for “Joe Bloggs” in “Altrincham”.

<soapenv:Body> 
  <hpw:AddressExpandResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID> 
       %+0%JOE@1||BLOGGS@2||ALTRINCHAMmx%uk-test-nc-extract-current %EnglishAndWelsh%yes%no%no
    </hpw:SID>  
  </hpw:AddressExpandRequest> 
</soapenv:Body>

AddressDetails Request

The AddressDetails request obtains the address and associated data for a specific matched item.

Generally a client would only obtain the details of matched items that contain a full address (i.e. those having the Expandable flag value no). However it is possible to obtain the details of any matched item.

It only requires the SID (Search IDentity) of the matched item to be expanded. This will have been obtained from either the initial search request or any AddressExpand request that followed.

All other parameters are optional and should only be supplied when a non-default configuration is required.

Below is an example AddressDetails request – continuing the search for “Joe Bloggs” in “Altrincham”.

<soapenv:Body>
  <hpw:AddressDetailsRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%JOE@1||BLOGGS@2||ALTRINCHAMmx%uk-test-nc-extract-current
      %single_step%250%EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressDetailsRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below).

Successful responses will also contain a single matched item. The content of the matched item is dependent on the requested options. It will contain a number attribute (value 1) and any combination of the elements listed below. For a basic request this will only be an address.

Below is an example AddressDetails response – continuing the search for “Joe Bloggs” in “Altrincham”.

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:Address>
        <hpw:Name>Mr Joe Bloggs</hpw:Name>
        <hpw:Line1>Hopewiser Ltd</hpw:Line1>
        <hpw:Line2>Merlin Court</hpw:Line2>
        <hpw:Line3>Atlantic Street</hpw:Line3>
        <hpw:Town>ALTRINCHAM</hpw:Town>
        <hpw:County>Cheshire</hpw:County>
        <hpw:Postcode>W14 5NL</hpw:Postcode>
        <hpw:DP>1HQ</hpw:DP>
      </hpw:Address>
    </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

How do I obtain an address from a given grid reference?

The AddressSearchByRadius function is used to drill down a hierarchy of matched items to locate a specific address and obtain its details. The minimum initial search criteria is a grid reference and a search radius (in metres). The address can be returned in a default format or can be customised into a formatted label. Individual address elements and additional data items may also be returned.

The actual search function is achieved via three separate requests; AddressSearchByRadius, AddressExpand and AddressDetails.

1. The AddressSearchByRadius request initiates the search for the given search criteria plus request options, and returns a list of matched items.
2. The AddressExpand request continues the search by expanding a specific matched item, and returns a new list of matched items at the next search level. This is repeated until no further expansion is possible.
3. The AddressDetails request obtains the address and associated data for a specific matched item.

NOTE: The AddressSearchByRadius function is only available when the Master Address File contains appropriate data. For further details please refer to the How do I discover the searching capability of a given MAF? section below.

Below is an example AddressSearchByRadius request for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
  <hpw:AddressSearchByRadiusRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:GridX>0375403</hpw:GridX>
    <hpw:GridY>0386044</hpw:GridY>
    <hpw:Radius>1</hpw:Radius>
  </hpw:AddressSearchByRadiusRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below). Please note if a search does not fully complete (i.e. find all possible matches), then the entire request will be treated as a failure and an appropriate status code/description will be returned (e.g. “Too many matches”).

Successful responses will also contain one or more matched items. Each matched item will contain a number attribute (a simple count) and the elements listed below.

Below is an example AddressSearchByRadius response for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
  <hpw:AddressSearchByRadiusResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:SID>
        %+0%386044@XM||391054@YM||1@RM_G%uk-rm-paf%single_step%250
        %EnglishAndWelsh%yes%no%no
      </hpw:SID>
      <hpw:Text>1 Berwick Avenue,Stockport,Cheshire</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
    <hpw:Match number="2">
      <hpw:SID>
        %+1%386044@XM||391054@YM||1@RMew%uk-rm-paf%single_step%250
        %EnglishAndWelsh%yes%no%no
      </hpw:SID>
      <hpw:Text>2 Berwick Avenue,Stockport,Cheshire</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
    ... etc ...
    <hpw:Match number="70">
      <hpw:SID>
        %+69%386044@XM||391054@YM||1@RMbk%uk-rm-paf%single_step%250
        %EnglishAndWelsh%yes%no%no
      </hpw:SID>
      <hpw:Text>87 Berwick Avenue,Stockport,Cheshire</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
  </hpw:AddressSearchByRadiusResponse>
</soapenv:Body>

Address Expand Request

The AddressExpandRequest continues a search, by expanding a specific matched item, and returns a new list of matched items at the next search level. This should be repeated until no further expansion is possible.

Matched items with either the Expandable flag value yes or the ExpandableToName* flag value yes can be expanded.

It only requires the SID (Search IDentity) of the matched item to be expanded. This will have been obtained from either the initial search request or a preceding AddressExpandRequest.

All other parameters are optional and should only be supplied when a non-default configuration is required.

Below is an example AddressExpanded request – continuing the search for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
  <hpw:AddressExpandRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+1%386044@XM||391054@YM||1@RMew%uk-rm-paf%single_step%250
      %EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressExpandRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below). Please note if a search does not fully complete (i.e. find all possible matches), then the entire request will be treated as a failure and an appropriate status code/description will be returned (e.g. “Too many matches”).

Successful responses will also contain one or more matched items. Each matched item will contain a number attribute (a simple count) and the elements listed below.

Below is an example AddressExpand response – continuing the search for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
<hpw:AddressExpandResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
  <hpw:StatusCode>5</hpw:StatusCode>
  <hpw:StatusDesc>Item cannot be expanded</hpw:StatusDesc>
  </hpw:AddressExpandResponse>
</soapenv:Body>

Address Details Request

The AddressDetails request obtains the address and associated data for a specific matched item.

Generally a client would only obtain the details of matched items that contain a full address (i.e. those having the Expandable flag value no). However it is possible to obtain the details of any matched item.

It only requires the SID (Search IDentity) of the matched item to be expanded. This will have been obtained from either the initial search request or the preceding AddressExpand request.

All other parameters are optional and should only be supplied when a non-default configuration is required.

Below is an example AddressDetails request – continuing the search for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
  <hpw:AddressDetailsRequest>
    <hpw:SID>
        %+1%386044@XM||391054@YM||1@RMew%uk-rm-paf%single_step%250
        %EnglishAndWelsh%yes%no%no
    </hpw:SID>
  </hpw:AddressDetailsRequest>
</soapenv:Body>

The response will always contain a status code and description (see Status Codes section below).

Successful responses will also contain a single matched item. The content of the matched item is dependent on the requested options. It will contain a number attribute (value 1) and any combination of the elements listed below. For a basic request this will only be an address.

Below is an example AddressDetails response – continuing the search for “an area of 1 metre within (0386044, 0391054)”

<soapenv:Body>
  <hpw:AddressDetailsResponse xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:Match number="1">
      <hpw:Address>
        <hpw:Line1>2 Berwick Avenue</hpw:Line1>
        <hpw:Town>STOCKPORT</hpw:Town>
        <hpw:County>Cheshire</hpw:County>        
        <hpw:Postcode>SK4 3AA</hpw:Postcode>
        <hpw:DP>1QD</hpw:DP>
      </hpw:Address>
    </hpw:Match>
  </hpw:AddressDetailsResponse>
</soapenv:Body>

How do I get version information?

<soapenv:Body>
  <hpw:VersionRequest/>
</soapenv:Body>

<soapenv:Body>
  <hpw:VersionResponse xmlns:hpw="http://hopewiser/soapaddrsvr">>
     <hpw:StatusCode>0</hpw:StatusCode>
     <hpw:StatusDesc>Successful</hpw:StatusDesc>
     <hpw:SoapAddrSvr>SOAP Address Server Version: 1.2.12</hpw:SoapAddrSvr>
     <hpw:Atlas>Atlas Version: 3.60.21 (fh:4.0.0 xfh:2.1.0)</hpw:Atlas>
  </hpw:VersionResponse>
</soapenv:Body>

How do I discover the searching capability of a given MAF?

<soapenv:Body>
  <hpw:IndexesRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:MAF>uk-test-xtra-current</hpw:MAF>
  </hpw:IndexesRequest>
</soapenv:Body>

<soapenv:Body>
  <hpw:IndexesResponse xmlns:hpw="http://hopewiser/soapaddrsvr">>
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    
    <hpw:RadiusSearchAllowed>0</hpw:RadiusSearchAllowed>
    <hpw:Indexes>
      <hpw:Index>ORGANISATION</hpw:Index>
      <hpw:Index>UDPRN</hpw:Index>
      ... etc ...
    </hpw:Indexes>
  </hpw:IndexesResponse>
</soapenv:Body>

The following table lists the output fields that can be retrieved from all Master Address Files (MAFs) where this is available in the reference data.

Each SOAP Address Service response message will contain a status code and status description, as defined in the following table.