Hopewiser SOAP Interface - ListAPI Call
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 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.
The structure returned by the ListAPI call is always an array but if multiple results are returned each result will have an ID associated with it. This ID can re-submitted to the ListAPI call to expand on this partial address.
If a single result is returned then this is a complete address and as such all the additional fields requested will 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:
| Input To ListAPI | Output From ListAPI |
hale road,altrincham |
address = [
...,
{
'ID' => '+0+1,hale road,altrincham',
'LABEL' => [
'+ Hale',
'+ Hale Road,Altrincham,Cheshire'
]
},
...
];
|
| +0+1,hale road,altrincham |
address = [
...,
{
'ID' => '+0+1+149,hale road,altrincham',
'LABEL' => [
' Hopewiser Ltd,187',
'+ Hale',
'+ Hale Road,Altrincham,Cheshire'
]
},
...
];
|
| +0+1+149,hale road,altrincham |
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 the 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 facility 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 as a call to the SOAP Server.
For instance, if a client 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.