SOAP API

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?’ 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.

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.

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

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

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.

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

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>

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?’ 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.

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.

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.

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.

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.

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.

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>

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.

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.

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

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

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.

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

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>

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

Example:

<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 status code 8 will be returned if the specified MAF does not contain any indexed fields.