Hopewiser Web Services

AH21

Obtains a list of matching premises for a given postcode from the Hopewiser SOAP Server.

Syntax

Addresses [] addresses = soap.ah21(string session_id, string input [, string data]);

where for example:

input = 'WA15 8DG,187';

data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';

addresses = [
              {
                'LABEL' => [
                             'Hopewiser Ltd',
                             '187 Hale Road',
                             'Hale',
                             'ALTRINCHAM',
                             'Cheshire',
                             'WA15 8DG',
                             'UNITED KINGDOM'
                           ],
                'DISTRICT_LEVEL' => [
                                      'Hopewiser Ltd',
                                      '187 Hale Road',
                                      'Hale'
                                    ],
                'TOWN' => 'ALTRINCHAM',
                'POSTCODE' => 'WA15 8DG',
                'COUNTY' => 'CHESHIRE',
                'COUNTRY' => 'UNITED KINGDOM'
              }
            ];

Usage

When a client application invokes the AH21 call, it passes in a Session ID, an input string (consisting of a postcode and an optional premise separated by a comma) and an optional data string (consisting of any additional fields which the user would like generated separated by commas). Upon invocation, the Hopewiser SOAP server authenticates the Session ID and returns a Addresses structure similar to that described above.

The LABEL element of the Addresses structure is ALWAYS returned whether or not a data string is provided. It is likely that this is the address that will be displayed to the user.

Modules

In order to make all datasets (e.g - UK, Australia, etc) available through a single interface the Module scheme has been introduced. This scheme allows clients to use the AH21 call to perform postcode lookups on their Default Dataset (in most cases just that of your country of origin) while also providing facility perform postcode lookups on other datasets using the same syntax.

In order to query a different dataset the required Module ID should be determined using the Modules call. This Module ID can then be used as a call to the SOAP Server.

For instance, if a client wanted to use the Australian Dataset for a Postcode Lookup the Modules call would reveal the following:

modules = [
            ...,
            {
              'CLASS'       => 'ah21',
              'COUNTRY'     => 'aus',
              'DESCRIPTION' => 'AH21PCIX Module - AUSTRALIAN data',
              'MODULE_ID'   => 'ah21_aus'
            },
            ...
          ];

So the Module ID we are interested in is ah21_aus and you would call this module as follows:

Addresses [] addresses = soap.ah21_aus(string session_id, string input [, string data]);

where the syntax is exactly the same as in the standard AH21 call.

Samples

Sample Request XML

Sample Response XML

---