Overview

The Hopewiser SOAP Address Service API is a web service that can be integrated to perform postcode lookup and (partial) address search operations within a client application. This has been tested as SOAP Basic Profile 1.1 compliant, using the WSI test tool.

Each request must be authenticated via a username/password combination, which is supplied in the SOAP header. To secure this information all requests should use the https:// protocol, in preference to http://.

Authentication

Authentication is based on the WS-Security UsernameToken, where the default password type (PasswordText) is applied. Each request must be authenticated via a username/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 (show above) are common to all requests.

Demo

Quick Start Guide

  • Need a Hopewiser AddressServer in the Cloud service account and a 'live' click bundle.

  • 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 Quick Start 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 (in the Basics section) using VB.NET samples and associated 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...

  • Search 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).

  • Other adaptations possible to personalise using the Customisations section.

1. SOAP API Quick Start Introduction

This introduction will use SoapUI, which is a quick and easy tool to make SOAP calls. 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

new project

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

project navigator

In the template request, replace the ? placeholders with the username and password you used when registering with AddressServer in the Cloud.

status request

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

On 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-internal), 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.

status request complete

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 and MAF. Remove all other options.

postcode lookup

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

postcode-lookup-complete

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

2. 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-internal
      </hpw:MAF>
    </hpw:Default>
    <hpw:Alternate>
      <hpw:MAF version="MAF Version 58 (UU)  UNITED KINGDOM  Built 20140408 GRID">
        uk-nspd-paf-internal
      </hpw:MAF>
    </hpw:Alternate>
  </hpw:StatusResponse>
</soapenv:Body>

1. How do I customise an address label?

The SOAP Address service defaults to return address labels that comprise a standard set of address elements.

If this does not meet your requirements, then you can request a formatted label by specifying an AddressType value of either formatted_label or both. The layout can then be customised by specifying the appropriate label formatting options.

Option Description
OrganisationFormat

Position of the organisation within the formatted label. Allowed values are fixed or free (default).

The value fixed reserves the first line of the formatted label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty.
LabelFormat

Position of the town, county and postcode within the formatted label. Allowed values are fixed_town, fixed_postcode or free (default).

The value fixed_town reserves the last three lines of the formatted label for the town, county and postcode and forces each value to be output on a separate line. A line is reserved for the county even if none is output.

The value fixed_postcode reserves the last line of the formatted label for the postcode and forces it to be output on a separate line.

When a fixed value is requested, the formatted label will comprise the maximum number of lines, as specified by the NumLines option (see below), some of which may be empty.
IncludeCounty

Controls when counties should be included within the formatted label. Allowed values are always, when_required (default) and never.

The value when_required will include the county when appropriate. For example when it meets PTT guidelines or when it is required to disambiguate UK town names.
DropCountyToFit Tries dropping the county if it does not fit within the formatted label. Allowed values are yes (default) or no.
CaseFormat Required character case. Allowed values are upper, ptt_convention (default) or mixed.
NumLines Maximum number of formatted output lines. Allowed range is 2 to 9 (default 6).
LineWidth Maximum number of characters per formatted output line. Allowed range is 10 to 56 (default 56).
DropNameFromLabel Removes the personal name from the formatted label. Allowed values are yes or no (default).

NOTE: This option is not applicable for Postcode Lookup requests.

Example Address Details Request - requesting a formatted label in uppercase where the last line is reserved for the postcode.

<soapenv:Body>
  <hpw:AddressDetailsRequest>
    <hpw:SID>
      %+2+0%DOWNING STREET||LONDONi8%uk-rm-paf-internal%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>

Each formatted label, returned in a SOAP Address Service response, will be comprised of a status attribute and up to nine address lines.

The status attribute may take the value ok, split_element or wont_fit. The value ok indicates that the address was successfully formatted. The value split_element also indicates that the formatting was successful, but an address element (e.g. house name) could not be accommodated on a single line, so was split onto a second line. The value wont_fit indicates that the address could not be formatted into the specified label dimensions (NumLines and LineWidth).

If successful then the formatted label will also contain a number of output address lines. The actual number of lines is dependent on the formatting options.

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

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

Example Address Details Request - requesting both the Country and Delivery Point fields.

<soapenv:Body>
    <hpw:AddressDetailsRequest>
      <hpw:SID>
        %+2+0%DOWNING STREET||LONDONi8%uk-rm-paf-internal%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>

 

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

The Extra Data 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 beyond those common to all MAFs, for example National Statistics Postcode Directory (NSPD) data.

An Extra Data Request may take an optional MAF parameter to identify the required MAF. If omitted the user's default MAF will be applied.

Example Extra Data Request for a MAF containing NSPD data.

<soapenv:Body>
    <hpw:ExtraDataRequest>
      <hpw:MAF>uk-nspd-paf-internal</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 obtained these extra data fields add an ExtraData tag to your request that specifies the name of each required item.

Example Address Details Request - requesting the grid reference fields.

<soapenv:Body>
  <hpw:AddressDetailsRequest>
    <hpw:SID>
      %+2+0%DOWNING STREET||LONDONi8%uk-nspd-paf-internal%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>

4. Address search from a given index

The Address Search By Index function is used to drill down a hierarchy of matched items to locate a specific address and obtain its details. The initial search criteria is an index name and value. 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; Address Search By Index, Address Expand and Address Details.

  1. The "Address Search By Index Request" initiates the search, for the given search criteria plus request options, and returns a list of matched items.

  2. The "Address Expand 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"Address Details Request" obtains the address and associated data for a specific matched item.

NOTE: The Address Search By Index 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.

Address Search By Index Request

An Address Search By Index Request requires both an Index and Value search parameter. The Index parameter must be the full name of an indexable field. The Value parameter specifies the search criteria within that field. It may contain single character (?) or multi character (*) wildcards, but must not start with a wildcard character.

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

Parameter Mandatory/Optional Description
Index Mandatory Name of index field to search.
The list of indexed fields can be obtained from an "Indexes" function.
Value Mandatory Index value search criteria.
MAF Optional Specifies which MAF the lookup should be performed against. If omitted the user's default MAF will be applied. Available MAFs are identified via the "Status" function.
RequestOptions Optional
  1. MaxMatches - the maximum number of matches to be returned in the response. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  3. IncludePersonNames - indicates if personal names should be included in the textual description of premise level matched items (e.g. "27 [SMITH]"). Allowed values are yes (default) and no. Note this option is only applicable when the MAF contains name data.

 

Example Address Search By Index Request for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

<soapenv:Body>
  <hpw:AddressSearchByIndexRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:Index>ORGANISATION</hpw:Index>
    <hpw:Value>Hopewiser Ltd</hpw:Value>
  </hpw:AddressSearchByIndexRequest>
</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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Search By Index response for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

<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-internal%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>


Address Expand Request

The Address Expand 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional

One option is available for an Address Expand Request.

  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.

 

Example Address Expanded Request - continuing the search for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

<soapenv:Body>
  <hpw:AddressExpandRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%@ORGANISATION@HOPEWISER LTD0p%uk-rm-paf-internal%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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Expand Response - continuing the search for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

<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 Address Details 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional
  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. AddressType - the address type to be returned. Allowed values are address (default), formatted_label or both (see the How do I customise an address label? section for further details).
FormattedLabelOptions Optional Eight options are available. These are used to customise the output formatted labels to meet the client's requirements (see the How do I customise an address label? section for further details).
Data Optional Specifies the common data items to be returned (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Optional Specifies the extra data items to be returned (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details Request - continuing the search for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

<soapenv:Body>
  <hpw:AddressDetailsRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%@ORGANISATION@HOPEWISER LTD0p%uk-rm-paf-internal%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.

Element Description
Address An address will be present when the AddressType request option has been omitted or contains either the value address or both (see 'Common Output Fields' section for further details).
FormattedLabel A formatted label will be present when the AddressType request option contains either the value formatted_label or both (see the 'How do I customise an address label?' section for further details).
Data Only requested common data items will be present (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Only requested extra data items will be present (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details Response - continuing the search for "Hopewiser Ltd" against the "ORGANISATION" indexed field.

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

5. Address search from a given personal name

The Address Search By Name 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 function is achieved via three separate requests; Address Search By Name, Address Expand and Address Details.

  1. The "Address Search By Name Request" initiates the search, for the given search criteria plus request options, and returns a list of matched items.

  2. The "Address Expand 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 "Address Details Request" obtains the address and associated data for a specific matched item.

 

NOTE: The Address Search By Name 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.
 

Address Search By Name Request

The Address Search By Name Request consists of three core parameters; the Forename, Surname and Address Filter (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 Address Filter is optional, but would generally be provided to narrow the search to a specific area. This could be a postcode, 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 Address Filter (Input1..Input10) should be given a value.

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

Parameter Mandatory/Optional Description
Forename Optional Forename search criteria.
Surname Optional Surname search criteria.
Input1..Input10 Optional Address filter - lines 1 to 10.
MAF Optional Specifies which MAF the lookup should be performed against. If omitted the user's default MAF will be applied. Available MAFs are identified via the "Status" function.
RequestOptions Optional
  1. MaxMatches - the maximum number of matches to be returned in the response. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.

 

Below is an example Address Search By Name Request for a fictitious person, "John Smith" in "Altrincham".

<soapenv:Body>
  <hpw:AddressSearchByNameRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:Forename>John</hpw:Forename>
    <hpw:Surname>Smith</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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Search By Name response for "John Smith" 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%JOHN@1||SMITH@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 John Smith]</hpw:Text>
      <hpw:Expandable>no</hpw:Expandable>
    </hpw:Match>
  </hpw:AddressSearchByNameResponse>
</soapenv:Body>


Address Expand Request

The Address Expand 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional

One option is available for an Address Expand Request.

  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.

 

Example Address Expanded Request - continuing the search for "John Smith" in "Altrincham".

<soapenv:Body>
  <hpw:AddressExpandRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%JOHN@1||SMITH@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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Expand Response - continuing the search for "John Smith" in "Altrincham".

<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 Address Details 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional
  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. AddressType - the address type to be returned. Allowed values are address (default), formatted_label or both (see the 'How do I customise an address label?' section for further details).
FormattedLabelOptions Optional Eight options are available. These are used to customise the output formatted labels to meet the client's requirements (see the 'How do I customise an address label?' section for further details).
Data Optional Specifies the common data items to be returned (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Optional Specifies the extra data items to be returned (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details Request - continuing the search for "John Smith" in "Altrincham".

<soapenv:Body>
  <hpw:AddressDetailsRequest xmlns:hpw="http://hopewiser/soapaddrsvr">
    <hpw:SID>
      %+0%JOHN@1||SMITH@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.

Element Description
Address An address will be present when the AddressType request option has been omitted or contains either the value address or both (see 'Common Output Fields' section for further details).
FormattedLabel A formatted label will be present when the AddressType request option contains either the value formatted_label or both (see the 'How do I customise an address label?' section for further details).
Data Only requested common data items will be present (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Only requested extra data items will be present (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details Response - continuing the search for "John Smith" 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 John Smith</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>

6. Address search from a given grid reference

The Address Search By Radius function is used to drill down a hierarchy of matched items to locate a specific address and obtain its details. The initial search criteria is a grid reference and search radius. 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; Address Search By Radius, Address Expand and Address Details.

  1. The "Address Search By Radius Request" initiates the search, for the given search criteria plus request options, and returns a list of matched items.

  2. The "Address Expand 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 "Address Details Request" obtains the address and associated data for a specific matched item.

 

NOTE: The Address Search By Radius 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.
 

Address Search By Radius Request

An Address Search By Radius request requires both a grid reference (GridX/GridY) plus a search Radius. All values must be specified in metres.

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

Parameter Mandatory/Optional Description
GridX Mandatory The Grid X coordinate in metres.
GridY Mandatory The Grid Y coordinate in metres.
Radius Mandatory The distance from a grid reference centre point (GridX, GridY).
MAF Optional Specifies which MAF the lookup should be performed against. If omitted the user's default MAF will be applied. Available MAFs are identified via the "Status" function.
RequestOptions Optional
  1. MaxMatches - the maximum number of matches to be returned in the response. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  3. IncludePersonNames - indicates if personal names should be included in the textual description of premise level matched items (e.g. "27 [SMITH]"). Allowed values are yes (default) and no. Note this option is only applicable when the MAF contains name data.

 

Example Address Search By Radius 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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Search By Radius 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-internal%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-internal%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-internal%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 Address Expand 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional

One option is available for an Address Expand Request.

  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.

 

Example Address Expanded 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-internal%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.

Element Description
SID The matched item's search identity. This is a unique reference that can be used to expand the item or obtain the item's address details.
Text A textual description of the matched item. This should be presented to the user for selection purposes.
Expandable A flag indicating if the matched item can be expanded to search for premise details. Possible values are yes or no. When the flag contains the value yes further address details can be obtained via an "Address Expand Request". When the flag contains the value no full address details can be obtained via an "Address Details Request".
ExpandableToName A flag indicating if the matched item can be expanded beyond premise details to return a list of resident names for the address. Possible values are yes or no.

 

Example Address Expand 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 Address Details 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 Address Expand Request.

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

Parameter Mandatory/Optional Description
SID Mandatory Search identity of a matched item
RequestOptions Optional
  1. Timeout - the timeout period, in seconds, to perform the request. The SOAP Address Service is provisioned with a default and upper limit. If a requested value exceeds the upper limit then the upper limit will be applied.
  2. AddressType - the address type to be returned. Allowed values are address (default), formatted_label or both (see the 'How do I customise an address label?' section for further details).
FormattedLabelOptions Optional Eight options are available. These are used to customise the output formatted labels to meet the client's requirements (see the 'How do I customise an address label?' section for further details).
Data Optional Specifies the common data items to be returned (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Optional Specifies the extra data items to be returned (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details 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-internal%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.

Element Description
Address An address will be present when the AddressType request option has been omitted or contains either the value address or both (see 'Common Output Fields' section for further details).
FormattedLabel A formatted label will be present when the AddressType request option contains either the value formatted_label or both (see the 'How do I customise an address label?' section for further details).
Data Only requested common data items will be present (see the 'How do I obtain individual address or common data fields' section for further details).
ExtraData Only requested extra data items will be present (see the 'How do I obtain additional (‘extra’) data items?' section for further details).

 

Example Address Details 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>

7. How do I get version information?

The Version function is used to obtain system information, identifying the version of the SOAP Address Service and the version of the underlying native Atlas library.

A Version Request does not require any parameters.

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

The response will always contain a status code and description (see Status Codes section below). Successful responses will also contain the version of the SOAP Address Service and the version of the underlying Atlas library.

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

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

The Indexes function is used to check the searching capabilities and to discover the list of available indexed fields. The MAF supports "index search" when indexed fields are available. The result will also show the NamesAvailable and RadiusSearchAllowed integer flags that indicate whether the opened MAF supports "name" and "radius search".

All MAFs support address searching from a given postcode, full or partial address. Some MAFs may contain additional data that also allows address searching from either a given index name and value, a personal name or a grid reference and radius.

These additional searching capabilities allow the retrieval of addresses using the methods listed below:

  • Address Search By Index

  • Address Search By Name

  • Address Search By Radius

An Indexes Request may take an optional MAF parameter to identify the required MAF. If omitted the user's default MAF will be applied.

Example Indexes Request against an "uk-test-xtra-current" MAF dataset.

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

The response will always contain a status code and description (see Status Codes section below). Please note that status code 8 will be returned if the specified MAF does not contain any indexable fields.

Successful responses will also contain integer tags to indicate if the MAF supports name searching (tag NamesAvailable) and/or radius searching (tag RadiusSearchAllowed). If the MAF supports index searching, then the response will also include a list of available index field names.

Address Searching Capabilities

Tag Value Description
NameAvailable 0
1
2
Name search is not supported.
Supports surname searching only.
Supports both forename and surname searching.
RadiusSearchAllowed 0
1
Radius search is not supported.
Supports radius searching.
Index Fieldname Indexed search is supported against the indexed Fieldname.

 

Example:

<soapenv:Body>
  <hpw:IndexesResponse xmlns:hpw="http://hopewiser/soapaddrsvr">>
    <hpw:StatusCode>0</hpw:StatusCode>
    <hpw:StatusDesc>Successful</hpw:StatusDesc>
    <hpw:NamesAvailable>0</hpw:NamesAvailable>
    <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 status code 8 will be returned if the specified MAF does not contain any indexed fields.

Common Output Fields

Data Item Description
department Department associated within an organisation
organisation Organisation name for a delivery point
formatted_flat Flat - formatted as if in a label
formatted_floor Floor - formatted as if in a label
formatted_premise_no Premise number - formatted as if in a label
formatted_pobox PO Box - formatted as if in a label
line1..line5 Up to five formatted address lines may be present
house_1 Primary house name for a delivery point
house_2 Secondary house name for a delivery point
street_1 First street of an address
street_2 Second street of an address
district_1 Minor district of an address
district_2 Major district of an address
town Town
county County
county_needed (UK Only) Value Y if the county is needed to distinguish a UK Postal Town, otherwise N
country Country
country_flag

(UK Only) An indicator of the country of the relevant Post Town for the address.

  • E - England

  • S - Scotland

  • N - Northern Ireland

  • I - Eire

  • M - Isle of Man

  • C - Channel Islands

  • W - Wales (Anglicised)

  • H - Wales (Harlech)

  • B - (both Anglicised and Harlech)

postcode Postcode
postcode_data Postcode plus delivery point
dp Three character Delivery Point Suffix (DPS) and checksum for an address
Eight character Delivery Point ID (DPID) in Australia
commercial

(UK Only)

  • R - Residential
  • S - Small user
  • L - Large user
dedup_key Key for deduplication purposes
extended_key Extended key used for deduplication purposes
uaid Unique address identifier
udprn (UK Only) Eight digit numeric code to uniquely identify a UK delivery point
st_name (Australia only) Street name without type
st_type (Australia only) Street type
st_suffix (Australia only) Street suffix
personal_name Resident name

Status Codes

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

Code Description
0 Successful
1 No match
2 Too many matches - exceeded num
3 Request timeout - exceeded num sec
4 MAF does not contain extra data
5 Item cannot be expanded
6 Search criteria is invalid or too vague
7 Error searching postcode index
8 MAF does not contain indexes
9 Search criteria contains too many inputs

SOAP Faults

The SOAP Address Service will return client SOAP faults (i.e. faultcode value Client) when the requesting message is badly formed or contains incorrect information. The faultstring will identify the reason for the failure:

  • invalid username/password

  • missing mandatory parameter

  • invalid parameter

  • MAF does not contain the requested extra data item

  • MAF access has been blocked

The SOAP Address Service will return a server SOAP fault (i.e. faultcode value Server) if it encounters an internal software error.