Address Validate API

Overview

Provides address validation services for validating if the inputted address is real and correcting addresses with minor mistakes.
The service follows RESTful principles – accepting HTTP requests and returning JSON or XML response documents.
For addresses which can not be validated, you can use one of our address lookup services such as AutoComplete API or Rest API to obtain the address

Quick Start

To use this functionality you will need to buy an Address Lookup click bundle from the Shop located in our Portal. Register for the Portal here.
An address lookup is initiated by supplying a URL for example:

https://cloud.hopewiser.com.au/address-validate/validate/aus-ap-paf?input=Suite 512 530 Little Collins St,MELBOURNE,VIC,3000

The Address Validate service defaults to return a free format address label, which may contain up to five address lines. The town is presented in uppercase and the State is always included in the label. If this does not meet your requirements, then you can customise the layout. For example to increase the number of address lines to eight and to fix the last address line for the postcode you can supply a URL of:

https://cloud.hopewiser.com/address-validate/validate/aus-ap-paf?input=Suite 512  530 Little Collins St,MELBOURNE,VIC,3000&OutputFields=Label8&LabelFormat=FixedPostcode

Authentication is achieved using HTTP Basic Authentication, where both the token username and password are supplied in the HTTP header. To secure this information all requests should use the https:// protocol, in preference to standard http:// .

Basics

To discover the Master Address Files (MAFs) that are configured for the authenticated user, supply a URL of the form.

https://cloud.hopewiser.com.au/address-validate/mafs

This will return a list of available MAF identities (for example).

{
  "Status": "OK",
  "Results": {
    "MAFs": [
      {
        "ID": "aus-ap-paf"
      },
      {
        "ID": "aus-psma-gnaf"
      }
    ]
  }
}

How do I validate an address?

An address validate is initiated by supplying a URL of the form.

https://cloud.hopewiser.com.au/address-validate/validate/maf?parameters

where:

maf is the identity of the Master Address File to which the lookup is applied
parameters is a set of request parameters

Only a single request parameter is required – the input string. All other parameters are optional and should only be supplied when a non-default setting is required. As is standard with URLs, each parameter must be separated by an ampersand (&) character.

The input string is denoted by the key ‘input‘. This is the address search criteria, which could be a postcode, full or partial address. Splitting address elements (e.g. premise name, street, town, etc.) into a comma separated value generally yields better results. Please note that the search criteria must be URL encoded.

Example address lookup request for “Suite 512 530 Little Collins St,MELBOURNE,VIC,3000”.

https://cloud.hopewiser.com.au/address-validate/validate/aus-ap-paf?input=Suite 512  530 Little Collins St,MELBOURNE,VIC,3000

This will return the following response:

{
  "status": "OK",
  "result": {
    "Status": "ADD MATCH",
    "Label1": "Suite 512  530 Little Collins St",
    "Label2": "MELBOURNE  VIC  3000",
    "Extra":  {
       "HPWORDINAL": "008543603",
   }
  }
 }

This will return a JSON response with three keys: status, result (optional) and statusDetails (optional).
The status indicates the status of the request. The following status can be returned:

Status	Description
OK	The address validation function was performed successfully. This doesn’t mean the address was validated but instead the action of validating the address was performed. Please refer to the status in the result to determine if the address was validated.
UNAUTHORISED	The credentials provided could not be authenticated. This will always be accompanied with a HTTP status of 401
MISSING PARAMETER	A required parameter was missing. This will only be returned if the parameter “input” is missing. This will always be accompanied with a HTTP status of 400.
BAD PARAMETER	A provided parameter couldn’t be processed. This will always be accompanied with a HTTP status of 400
LICENCE_ERROR	The provided credentials doesn’t have permission to access the specified MAF. This will always be accompanied with a HTTP status of 401
OPEN_ERROR	The requested resource could not be opened. Specific details can be obtained from the description. This will always be accompanied with a HTTP status of 400
INTERNAL_ERROR	A unspecified error has occurred. This will always be accompanied with a HTTP status of 500

The JSON key “result” will only be returned for a status of “OK”. The JSON key “statusDetails” will only be returned for none “OK” statuses.

The JSON key “statusDetails” will always contain a JSON object with the following values:

Key	Description
description	A brief description explaining why the specific error status was returned

The JSON key “results” will always contain a JSON object which can contain the following items:

Data Item	Description
Label1-Label9	Formatted address label comprising up to the specified number of lines.
Extra	JSON Object of extra data. Key will always be the extra data name and the value will be the extra data value
Department	Department associated within an organisation
Organisation	Organisation name for a delivery point
Flat	Flat – formatted as if in a label
Floor	Floor – formatted as if in a label
Premise	Premise number – formatted as if in a label
POBox	PO Box – formatted as if in a label
Housename1	Primary house name for a delivery point
Housename2	Secondary house name for a delivery point
Streetname1	First street of an address
Streetname2	Second street of an address
Districtname1	Minor district of an address
Districtname2	Major district of an address
Town	Town
County	State
Postcode	Postcode
Country	Country
DPID	The delivery point suffix
UDPRN	(UK Only) Eight digit numeric code to uniquely identify a UK delivery point
UAID	Unique address identifier
DedupeKey	Key for deduplication purposes
ExtendedDedupeKey	Key for deduplication purposes

By default, only the Status, Label1-9 and Extra fields will be returned. Extra information can be obtained by providing the query parameter “OutputFields”. This field accepts a comma seperated list of fields which can be returned to obtain the desired field.

For example, the following URL can be used :

https://cloud.hopewiser.com.au/address-validate/validate/aus-ap-paf?input=Suite 512 530 Little Collins St,MELBOURNE,VIC,3000&OutputFields=town,postcode

This will return the following:

{
  "status": "OK",
  "result": {
    "Status": "ADD MATCH",
    "Label1": "Suite 512  530 Little Collins St",
    "Label2": "MELBOURNE  VIC  3000",
    "Extra":  {
       "HPWORDINAL": "008543603",
    },
    "Postcode": "3000",
    "Town": "MELBOURNE"
  }
 }

The Address validate service defaults to return a free format address label, which may contain up to seven address lines. The town is presented in uppercase and the State is always included in the label.

If this does not meet your requirements, then you can customise the layout. For example to increase the number of address lines to eight add the URL parameter “OutputFields=Label5“. To fix the last address line for the postcode add the parameter “LabelFormat=FixedPostcode“.

https://cloud.hopewiser.com/address-validate/validate/aus-ap-paf?input=Suite 512 530 Little Collins St,MELBOURNE,VIC,3000&OutputFields=Label8&LabelFormat=FixedPostcode

The following table lists the Label Parameter options available.

Label Parameters
Option	Description
OutputFields	This parameter is used to specify the required output fields within a selected item. It can be used to define the maximum number of lines in a formatted address label, by specifying a label value from Label1 to Label9. The default is Label7.
LabelFormat	Select the position of the Town, State and Postcode within the formatted address label. Allowed values are Standard (the default), FixedPostcode or FixedTown. The value FixedPostcode reserves the last line of the formatted address label for the postcode and forces it to be output on a separate line. The value FixedTown reserves the last three lines of the formatted address label for the town, state and postcode and forces each value to be output on a separate line. Please note that a line is reserved for the State even if none is output. When a fixed value is requested, the formatted address label will comprise the maximum allowed number of address lines, some of which may be empty.
ReserveOrganisationLine	Select the position of the organisation within the formatted label. Allowed values are AsRequired (the default), Always or Never. The value AsRequired includes the organisation within the address label following standard formatting rules. The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty. The value Never removes the organisation from the formatted address label.
IncludeCounty	Select when the State should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default). The value AsRequired will only include the State when appropriate, for example when it meets PTT guidelines or when it is required to disambiguate town names.
DropCountyToFitLabel	Select if the State may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default) or Always.
TownFormat	Select the required town format. Allowed values are Uppercase (the default) or Lowercase.

Address Validate API

Overview

Quick Start

Basics

How do I validate an address?

Authorisation Code