eSAM address web service
Access accurate and standardised address and geospatial data.
Pātiki and Waharua Kōpito patterns
On this page
Brief description
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, Statistics New Zealand and Health NZ.
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.
Accessible data
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, deprivation decile, and deprivation quintile.
eSAM has the following operations:
- Suggest address: The SuggestAddress request is called every time a character is typed into an application that has implemented the address predictive search.
-
Find address: 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.
- Address details: The GetAddressDetails request returns information for a single address from either the SuggestAddress or FindAddress results.
-
Get extra details: The GetExtraDetails request returns information for a single meshblock from the GetAddressDetails results.
- Get CAU extra details: 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 and implementation
Onboarding will transition to the DSH, but in the interim use the legacy method below. To use the eSAM services, download and complete the eSAM address web services request form from the page below:
Addressing and geocoding information for health providers
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 to identify 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 on the 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 the integration guide through the link below:
Addressing and geocoding information for health IT developers