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] [, string dataset]);
where for example:
input = 'atlantic street,altrincham';
data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';
dataset = 'uk-rm-paf';
address = [
{
'ID' => '%+0%ATLANTIC STREET||ALTRINCHAM',
'LABEL' => [
'+ Aegean Road,Atlantic Street,Broadheath,Altrincham',
]
},
...
{
'ID' => '%+6%ATLANTIC STREET||ALTRINCHAM',
'LABEL' => [
'+ Atlantic Street,Altrincham'
]
},
...
];
or:
input = '%+1+0+6%ATLANTIC STREET||ALTRINCHAM';
data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';
dataset = 'uk-rm-paf';
address = [
{
'LABEL' => [
'Hopewiser Ltd',
'Merlin Court',
'Atlantic Street',
'ALTRINCHAM',
'Cheshire',
'WA14 5NL',
'UNITED KINGDOM'
],
'DISTRICT_LEVEL' => [
'Hopewiser Ltd',
'Merlin Court',
'Atlantic Street',
],
'TOWN' => 'ALTRINCHAM',
'POSTCODE' => 'WA14 5NL',
'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 commas) and an optional data string (consisting of any additional Data 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 be 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 Data Fields requested will also be returned.
For instance, a search to find the full address of Hopewiser Ltd from a partial address of Atlantic Street, Altrincham would take the following steps:
| Input to ListAPI | Output from ListAPI |
|---|
| atlantic street,altrincham | address = [
...,
{
'ID' => '%+6%ATLANTIC STREET||ALTRINCHAM',
'LABEL' => [
'+ Atlantic Street,Altrincham'
]
},
...
]; |
| %+6%ATLANTIC STREET||ALTRINCHAM | address = [
...,
{
'ID' => '%+1+0+6%ATLANTIC STREET||ALTRINCHAM',
'LABEL' => [
' Hopewiser Ltd',
'+ Merlin Court',
'+ Atlantic Street,Altrincham'
]
},
...
]; |
| %+1+0+6%ATLANTIC STREET||ALTRINCHAM | address = [
{
'LABEL' => [
'Hopewiser Ltd',
'Merlin Court',
'Atlantic Street',
'ALTRINCHAM',
'Cheshire',
'WA14 5NL',
'UNITED KINGDOM'
],
'DISTRICT_LEVEL' => [
'Hopewiser Ltd',
'Merlin Court',
'Atlantic Street'
],
'TOWN' => 'ALTRINCHAM',
'POSTCODE' => 'WA14 5NL',
'COUNTY' => 'CHESHIRE',
'COUNTRY' => 'UNITED KINGDOM'
}
]; |
And so we are able to reach our complete address in three steps.
Choosing a dataset
If you have purchased access to more than one dataset, you can specify which you would like to use in the Dataset input (not to be confused with the data string). If you omit the field, provide an empty field or use the value “default”, the default for the login associated with the session is used. A typical dataset name is uk-rm-paf which indicates the Royal Mail PAF for UK data. Contact your account holder for information on which datasets you should have access to; they will have been provided with the information or you can contact our support team.
Sample – Multiple Partial Addresses and Single Complete Address
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<namesp1:listapiResponse>
<addresses>
<address>
<ID>%+0+0+0%WA14 5NL</ID>
<LABEL>
<item> Carol Nash Training Centre</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
<address>
<ID>%+1+0+0%WA14 5NL</ID>
<LABEL>
<item> Hopewiser Ltd</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
<address>
<ID>%+2+0+0%WA14 5NL</ID>
<LABEL>
<item> Matrix Telmatics Ltd</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
<address>
<ID>%+3+0+0%WA14 5NL</ID>
<LABEL>
<item> Northern Monitoring Services</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
<address>
<ID>%+4+0+0%WA14 5NL</ID>
<LABEL>
<item> T I C Group Ltd</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
<address>
<ID>%+5+0+0%WA14 5NL</ID>
<LABEL>
<item> UK Coach Search Ltd</item>
<item>+ Merlin Court</item>
<item>+ Atlantic Street,Altrincham,Cheshire</item>
</LABEL>
</address>
</addresses>
</namesp1:listapiResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
