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

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.

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.

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.

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:

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.

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:

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

4. Sample Code

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.