1. Functions

Contents

  • Login Login to use the service
  • Version Retrieve version information
  • AH21 Postcode lookup
  • ListAPI Partial address lookup
  • Logout End address lookup session

If an error occurs during the invocation of a SOAP call, the Hopewiser SOAP service returns a SOAP fault element. This fault element contains details such that the type of the error may be determined.

When upgrading from the original SOAP service:

  • The "status" function is no longer required because you will now receive your usage counts and expiry information in a regular automated report.
  • The "modules" function is no longer needed because you can now select a dataset using the the "dataset" field in the Version, AH21 and ListAPI functions.

 

Login

Logs in to the Hopewiser SOAP server and starts a client session.

Syntax

string session_id = soap.login(string login, string password);

Usage

When a client application invokes the Login call, it passes in a user name and password. Upon invocation, the Hopewiser SOAP server authenticates the login and returns the Session ID for the session. This session ID must be used in all subsequent calls to the Hopewiser SOAP server.

Client applications do not need to explicitly log out to end the session. Sessions expire automatically after a period of inactivity.

Samples

Sample Request XML

Sample Response XML

 

Version

Obtains SOAP Server version information from the Hopewiser SOAP Server. The Module Id should be omitted or left blank.

If you have purchased access to more than one dataset, you can specify which you would like to use in the Dataset input. If you omit the field, provide an empty value or use the value "default", the default for the login associated with the session is used. A typical dataset name is uk-rm-paf-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. Contact your account holder for information on which datasets you should have access to. They will have been provided with the information or can contact our support desk.

Syntax

Version version = soap.version(string session_id , "" [, string dataset]);

where for example:

version = {
            'SERVER' => 'SOAPAtlas Version: A/S 1.0.25',
            'ATLAS'  => 'Atlas Version: 3.50.01 (fh:3.5.0 xfh:2.0.0)',
            'PAF'    => 'MAF Version 34 (U )  UNITED KINGDOM  Built 20120321',
          };

Usage

When a client application invokes the Version call, it passes in a Session ID and an optional Dataset. Upon invocation, the Hopewiser SOAP server authenticates the Session ID and returns a Version structure similar to that described above.

Samples

Sample Request XML

Sample Response XML

 

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] [, string dataset]);

where for example:

input = 'WA14 5NL,HOPE*';

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

dataset = 'uk-rm-paf-internal';

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

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 value or use the value "default", the default for the login associated with the session is used. A typical dataset name is uk-rm-paf-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. 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.

Samples

Sample Request XML

Sample Response XML

 

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-internal';

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-internal';

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 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 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-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. 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 1 - Multiple Partial Addresses

Sample Request XML

Sample Response XML

Sample 2 - Single Complete Address

Sample Request XML

Sample Response XML

 

Logout

Ends the current client session on the Hopewiser SOAP server.

Syntax

int success = soap.logout(string session_id);

Usage

When a client application invokes the Logout call, it passes in a Session ID. Upon invocation, the Hopewiser SOAP server ends the associated client session.

Client applications do not need to explicitly log out to end the session. Sessions expire automatically after a period of inactivity.

Samples

Sample Request XML

Sample Response XML

2. Data Fields

Any call returning address data provides an optional input which allows the user to request more information than would otherwise be returned.

The default data and optional parameter are described for each function that provides this functionality.

Data Item Description
COUNTRY String field containing the country
COUNTRY_FLAG (UK only) - An indicator of the country of the relevant Post Town for the address. The codes are as follows:
  • E - England
  • S - Scotland
  • N - Northern Ireland
  • I - Eire
  • M - Isle of Man
  • C - Channel Islands
  • W - Wales (Anglicised)
  • H - Wales (Harlech)
  • B - Wales (both Anglicised and Harlech)
Note that for addresses close to the border between countries, the applicable Post Town may not necessarily be in the same country.
COUNTY String field containing the county
DEDUP_KEY String field containing a key for deduplication purposes
DEPARTMENT String field containing the department associated with an organisation where one exists
DISTRICT_1 String field containing the minor district of an address
DISTRICT_2 String field containing the major district of an address
DISTRICT_LEVEL An array containing formatted sub-premise, premise, street and district level information
DPS String field containing a 3-character DPS and checksum for the address or 8-character DPID in Australia 8-character DPID in Australia or String field containing a 3-character DPS and checksum for the address
FORMATTED_FLAT String field containing the flat, formatted as if in a label
FORMATTED_FLOOR String field containing the floor, formatted as if in a label
FORMATTED_PREMISE_NO String field containing the premise number, formatted as if in a label
HOUSE_1 String field containing the primary house name for a delivery point (where one exists)
HOUSE_2 String field containing the secondary house name for a delivery point (where one exists)
ORGANISATION String field containing the organisation name for a delivery point (where one exists)
POSTCODE String field containing the postcode
STREET_1 String field containing the first street of the address
STREET_2 String field containing the second street of the address
ST_NAME (Australia only) - String field containing the street name without type
ST_TYPE (Australia only) - String field containing the street type
TOWN String field containing the town
UAID String field containing a unique address identifier

 

When PAF+NSPD data is referenced (passing "uk-nspd-paf-internal" as the dataset to ah21 or listapi) instead of plain PAF, the Extra Data fields listed below will also become available.

Data Item Description
GRID_X String field containing the X-part of the grid reference
GRID_Y String field containing the Y-part of the grid reference

 

When Market Location data is referenced (passing "uk-ml-plus" as the dataset to ah21 or listapi) instead of PAF, the Extra Data fields listed below will also be available. Note that fields are only populated when the specific data is available.

Data Item Description
CRO_NUMBER Company Registration Number. This is an 8-digit number padded with leading zeroes where necessary, e.g. 01234567.
TURNOVER The company's turnover in pounds.
OFFICE_TYPE Provides an indication of whether a particular site is the head office, a branch or just a single site. The codes are as follows:
  • H - Head Office
  • B - Branch
  • S - Single Site
  • X - Unknown
FAX_No The company's fax number.
SIC_DESCRIPTION Description, maximum 80 characters, of the company's business, e.g. HAIRDRESSING AND OTHER BEAUTY TREATMENT.
EXEC_JOB_TITLE The senior executive's job title.
EXEC_SURNAME The senior executive's surname.
EXEC_FIRST_NAME The senior executive's first name.
EXEC_TITLE The senior executive's title, e.g. MR, MRS.
EMPLOYEE_BAND Provides an indication of the number of employees. The codes are as follows:
  • A - 1-4
  • B - 5-9
  • C - 10-19
  • D - 20-49
  • E - 50-99
  • F - 100-199
  • G - 200-499
  • H - 500-999
  • I - 1000+
  • X - Unknown
EMPLOYEE_COUNT The number of employees.
URN The Unique Reference Number of the company, e.g. ABCD123.
HEADING_DESCRIPTION A generic description of the company, e.g. BARBERS.
HEADING_CODE Code that correlates with the Heading Description.
SIC_CODE Identification code that correlates with the SIC Description.
TELEPHONE_NO The company's telephone number.

3. Status Codes

If an error occurs during the invocation of a SOAP call, the Hopewiser SOAP server returns a SOAP fault element containing information related to the error.

Possible error codes returned are as follows:

Code Error Name Description
10000 Fatal Error This error code is returned when an internal error occurs processing the request. If the error persists, please contact support with as much information as possible.
10001 Atlas Error This error code is returned when a general Atlas error occurs. For instance, no match could be found or the search matched too many entries.
10002 Login Error This error code is returned when an error occurs during the Login call. For instance, an invalid token username / password combination may have been provided.
10003 Session Error This error code is returned when an invalid Session ID is used. For instance, the Session ID may have expired.
10004 Timeout Error This error code is returned when a request takes too long and times-out. Requests will time-out if they take longer than 5 seconds to process.
10005 Field Error This error code is returned when an item is requested as data which does not exist. Check Data Fields for a list of valid fields.
10006 Permission Error This error code is returned when the login does not have permission to perform the action that was requested. Either you have no credit available or you have requested a dataset for which you do not have credit.
10007 Input Error This error code is returned when there is a problem with the request. Either the request is malformed or a non-existent dataset was requested.

 

Sample

 

Sample Fault Response XML (Search Error)

Sample Fault Response XML (No such dataset)

4. Sample Code

We have .NET sample code available for download

.NET SOAP Sample

.NET SOAP Sample Documentation (PDF)

Atlas Client API

The Atlas Client API is a C based library comprising a range of software modules that access address data held on Hopewiser's AddressServer. It provides the ability to:

  • validate an input address against a Master Address File (MAF)
  • retrieve all addresses from a given postcode
  • retrieve the delivery points for a given postcode and premise combination
  • search for streets
  • search for localities
  • search for premises/sub-premises
  • format addresses according to the appropriate postal convention

 

Atlas Client API ships as part of the standard Atlas Development Kit, which includes complete documentation and sample integrations with various languages.

 

The development kit is not available as a download. To obtain a copy please contact us.

It has an identical interface to the standard Atlas Development Kit allowing standalone applications to be switch to a web based solution by simply changing the underlying library and pointing it to your Web Service Account.

Users migrating from standalone Atlas will only need to change the path parameter given to the AH50FH_Open function from a local pathname to a URL of the form.

http://tokenusername:tokenpassword@cloud.hopewiser.com/addrsvr[?maf=optional-maf-id]

The optional-maf-id should be selected from those available within your account. If omitted the user's default MAF will be applied (providing it has been defined).