eSAM Address Web Service

Overview

eSpatial Address Management (eSAM) is an address validation service that provides accurate and standardised address and geospatial data. It uses data from New Zealand Post, Land Information New Zealand (LINZ), Statistics New Zealand (StatsNZ) and the Ministry of Health (MoH).

When used within a healthcare application, eSAM provides a set of address search and lookup services. It exposes public information and does not contain patient identifiable details or clinical data.

eSAM API

eSAM allows a software application to perform an address search using predictive text, or an address search by supplying a list of address strings.

It also includes functionality to return geospatial data associated with a validated address, including meshblock, Census Area Unit, Domicile Code, DHB Code, Deprivation Decile, and Deprivation Quintile.

eSAM has the following operations.

The SuggestAddress request is called every time a character is typed into an application that has implemented the address predictive search.

The FindAddress request returns a list of candidate addresses from up to five text fields. Each address listed includes a match / confidence score which indicates how closely the address matches the input supplied.

The GetAddressDetails request returns information for a single address from either the SuggestAddress or FindAddress results.

The GetExtraDetails request returns information for a single meshblock from the GetAddressDetails results.

The GetCAUExtraDetails request returns information for a single Census Area Unit from the GetExtraDetails results.

eSAM can integrate into applications through:

the type-ahead address input field integrated into a webpage using HTML and JavaScript — this uses a REST protocol, where the request is passed to the web service via HTTP GET, and results returned as JSON
using five address input fields passed to FindAddress using SOAP, over the HTTP POST protocol. An example of this would be a five-line search form displayed on a webpage.

Who can use this API

Authorised health provider organisations and users can use eSAM.

Onboarding

To use the eSAM services, download and complete the eSAM Address Web Services Request Form from the 'Downloads' section on this Ministry of Health page.

Addressing and geocoding information for health providers(external link)

When the form is complete, email your application to onlinehelpdesk@health.govt.nz.

Once your application has been processed, you will be authorised and advised of your ‘HPI Organisation ID’ and unique application identifier, which will be used as identification you when you use the services.

Once integration of eSAM within a local application is complete, a compliance test will be done before live production access is approved.

Technical

There is no authentication required to use eSAM but the end users HPI Organisation ID must be provided in the message header. The APIs can be used over Connected Health or over public internet.

Integrating eSAM into your application is dependent upon language and development environment. Integrated Development Environments (IDE) will typically provide plugins or have features that allow for the integration of SOAP and REST Web Service calls.

Find specifications, the User Guide, and Integration Guide on the Ministry of Health website.

Addressing and geocoding information for health IT developers(external link)