Hopewiser Web Services

ListAPI

Searches using at least two address elements on the Hopewiser SOAP Server.

Syntax

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

where for example:

input = 'hale road,altrincham';

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

address = [
            {
              'ID' => '+0+0,hale road,altrincham',
              'LABEL' => [
                           '+ [no district]',
                           '+ Hale Road,Altrincham,Cheshire'
                         ]
            },
            {
              'ID' => '+0+1,hale road,altrincham',
              'LABEL' => [
                           '+ Hale',
                           '+ Hale Road,Altrincham,Cheshire'
                         ]
            },
            {
              'ID' => '+0+2,hale road,altrincham',
              'LABEL' => [
                           '+ Hale Barns',
                           '+ Hale Road,Altrincham,Cheshire'
                         ]
            }
          ];

or:

input = '+0+1+149,hale road,altrincham';

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 ListAPI call, it passes in a Session ID, an input string (consisting of at least two address elements separated by a commas) 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 an 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.

The structure returned by the ListAPI call is always an array:

• If multiple results are returned, each result will be a partial address and contain an ID. An ID can re-submitted to the ListAPI call to expand on that partial address.
• If a single result is returned it may or may not contain an ID. If it does contain an ID, the result is a partial address. The ID can be resubmitted to the ListAPI call to expand the partial address.
• If a single result is returned and it does not contain an ID, the result is a complete address and as such any additional fields requested will also be returned.

For instance, a search to find the full address of Hopewiser Ltd from a partial address of Hale Road, Altrincham would take the following steps:

address = [
            ...,
            {
              'ID' => '+0+1,hale road,altrincham',
              'LABEL' => [
                           '+ Hale',
                           '+ Hale Road,Altrincham,Cheshire'
                         ]
            },
            ...
          ];

address = [
            ...,
            {
              'ID' => '+0+1+149,hale road,altrincham',
              'LABEL' => [
                           '  Hopewiser Ltd,187',
                           '+ Hale',
                           '+ Hale Road,Altrincham,Cheshire'
                         ]
            },
            ...
          ];

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'
              }
            ];

And so we are able to reach our complete address in three steps.

Modules

In order to make all datasets (e.g. UK, Australia, etc.) available through a single interface, a Module scheme has been introduced. This scheme allows clients to use the ListAPI call to perform address lookups on their default dataset (in most cases just that of your country of origin) while also providing the facility to perform address 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 in a call to the SOAP Server.

For instance, if you wanted to use the Australian dataset for an address lookup, the Modules call would reveal the following:

modules = [
            ...,
            {
              'CLASS'       => 'listapi',
              'COUNTRY'     => 'aus',
              'DESCRIPTION' => 'ListAPI Module - AUSTRALIAN data',
              'MODULE_ID'   => 'listapi_aus'
            },
            ...
          ];

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

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

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

Sample 1 - Multiple Partial Addresses

Sample Request XML

Sample Response XML

Sample 2 - Single Complete Address

Sample Request XML

Sample Response XML

Example

To see the ListAPI in action please visit the Hopewiser Address Search