Address Verification API (NZ)

Build
Send
Response
Errors

This page contains the technical information for our Address Verification API. For information about our Bulk Cleansing service, which makes use of this API, please see our Bulk Cleansing page.

The Address Verification API takes an address (potentially containing spelling mistakes and/or other errors) and attempts to match it against a valid address record in the Addressfinder database.

FAQ: How do I get the best results from Address Verification?

Build the GET request URL

Use the form below to build your request URL from the available parameters. The URL string will be generated and can be sent to the API in order to provide insight into how the API works and the response it returns. Or, if you are using Postman for your investigation, development and testing, include the desired parameters and copy and paste the request URL below into Postman's GET request URL field.

Field Name	Value	Type	Description
key *		String	Your unique licence key (find on Portal credentials)
secret *		String	Your unique secret key (find on Portal credentials). Alternatively, you can pass your secret key into the Authorization header of the request as such: `Authorization: your-secret`. FAQ: Learn more about authenticating direct API calls in request headers
q *		String	The address to be verified.
format *		String	The format of the response.
	Options json `json` for a response in json format. xml `xml` for a response in xml format.
post_box		String	This filter includes/excludes PO Box style addresses.
	Options Exclude PO Box addresses `0` PO Box only `1` Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types.
region_code		String	Will only match and return an address if exists within the selected region (Regional Authority). Including a region can improve your match success rate as it removes the possibility of matching addresses outside the selected region.
	Options Auckland `1` Bay of Plenty `2` Canterbury `3` Gisborne `4` Hawke's Bay `5` Manawatū-Whanganui `6` Marlborough `7` Nelson `8` Northland `9` Otago `A` Southland `B` Taranaki `C` Tasman `D` Waikato `E` Wellington `F` West Coast `G` Chatham Islands `H`
census		Integer	Desired data source for Statistics NZ census related metadata.
	Options 2018 `2018` census (default) 2023 `2023` census
domain		String	Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. FAQ: learn more about the domain parameter
ascii		Integer	A filter that replaces macron-containing characters with their ASCII counterparts. It doesn't exclude addresses with macron characters from the results, it translates these characters into their corresponding English equivalents within the addresses. Use when your systems are having issues processing macron-containing addresses.
	Options Converted `1` Converts the response to ASCII. Original Leaves the response as is, potentially containing macrons or non-ascii characters.

* Parameters marked with an asterisk are mandatory for this API call.

Request URL

https://api.addressfinder.io/api/nz/address/verification/

      
        /* Click the button above to see a real API response here */
        {
          "success": true
        }

Response Specification

The API response will include all the attributes associated with the matched address in the format requested in the API request. Empty attributes for the matched address will not be returned in the response.

Field Name	Type	Description	Example
`a`	String	Canonical address as supplied by Land Information New Zealand or NZ Post.	Unit 2, 1703A State Highway 1, Warkworth 0983
`postal`	String	Associated postal address when supplied by NZ Post. Field will be omitted if this address is not delivered to by NZ Post. FAQ: postal address vs 'a' address.	Unit 2, 1703A State Highway 1, RD 3, Warkworth 0983
`building_name`	String	Holds the building or property name.	Miban Building
`unit_type`	String	Describes the category of a sub-dwelling.	flat
`unit_identifier`	String	Identifies a specific sub dwelling. Can be alpha, number or a combination.	1
`floor`	String	The level number and level type in a multi-story building.	Level 19
`number`	String	The street number of the address. Also populated with the box number for PO Box type addresses.	1703
`alpha`	String	Holds the alpha component of a street number. In the address 1B High Street, B is the alpha.	B
`street`	String	Holds the full name and type of the street.	Pūrākaunui Road
`street_name`	String	Holds the full name of the street.	Pūrākaunui
`street_type`	String	The type of street.	avenue
`street_suffix`	String	The suffix of the street. Typically contains a compass direction.	North
`post_street`	String	Holds the street name and type from NZ Post, it will be omitted if the address is not delivered to by NZ Post.	Purakaunui Road
`post_street_name`	String	Holds the street name from NZ Post, it will be omitted if the address is not delivered to by NZ Post.	Purakaunui
`suburb`	String	The suburb or locality of the address as assigned by Land Information New Zealand.	Warkworth
`city`	String	The city, town or locality name as assigned by Land Information New Zealand.	Warkworth
`box_type`	String	The type of PO Box/CMB/Private Bag/Counter Delivery.	PO Box
`lobby_name`	String	The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located.	Fendalton
`rd_number`	String	The rural delivery number assigned by NZ Post to a rural address.	4
`post_suburb`	String	Name of the suburb when supplied by NZ Post.	Manukau
`mailtown`	String	Name of the town/city when supplied by NZ Post.	Warkworth
`postcode`	String	Holds the four digit postcode.	0983
`dpid`	String	A unique reference number assigned to each delivery address by NZ Post. If a value is present, then this address can be delivered to by NZ Post.	2668726
`primary_parcel_id`	String	The unique identifier of the portion of land associated with the selected address.	3866475
`aims_address_id`	String	The unique identifier from Land Information New Zealand (LINZ).	1518959
`x`	String	Longitude coordinate (in WGS84 format).	174.643199
`y`	String	Latitude coordinate (in WGS84 format).	-36.426956
`meshblock`	String	The meshblock identifier for the requested census dataset (see `census` parameter). If not specified, the census parameter will default to 2018.	146004
`sa1_id`	String	The Statistical Area 1 identifier for the requested census dataset (see `census` parameter). If not specified, the census parameter will default to 2018.	7000001
`sa2_id`	String	The Statistical Area 2 identifier for the requested census dataset (see `census` parameter). If not specified, the census parameter will default to 2018.	100200
`sa2`	String	The Statistical Area 2 name for the requested census dataset (see `census` parameter). If not specified, the census parameter will default to 2018.	Rangaunu Harbour
`rural`	Boolean	An indicator to help determine if this address is located in a rural setting. Note: Different courier companies have different rural/urban boundaries so this determination should be confirmed by your delivery agent.	true
`ur`	String	Urban rural name.	Kaimaumau
`ur_id`	String	Urban rural ID.	1002
`iur`	String	Urban rural indicator name.	Rural settlement
`iur_id`	String	Urban rural indicator ID.	21
`region`	String	The Regional Authority in which this address exists. Note: Regional Authorities are the top tier of local government in New Zealand.	Auckland Region
`region_id`	String	Region ID.	04
`ta`	String	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand.	Auckland
`ta_id`	String	Territorial Authority ID.	060
`con`	String	Constituency name.	Te Hiku Constituency
`con_id`	String	Constituency ID.	0101
`maoricon`	String	Maori Constituency name.	Okurei Maori Constituency
`maoricon_id`	String	Maori Constituency ID.	0402
`ward`	String	Ward name.	Banks Peninsula Ward
`ward_id`	String	Ward ID.	06016
`cb`	String	Community Board name.	Te Hiku Community
`cb_id`	String	Community Board ID.	00101
`tasub`	String	Territorial Authority Subdivision name.	Akaroa Subdivision
`tasub_id`	String	Territorial Authority Subdivision ID.	06019
`landwater`	String	Land/Water description.	Inlet
`landwater_id`	String	Land/Water ID.	22
`address_line_1`	String	First line of the non-suburb/city/postcode portion of the address.	Unit 2
`address_line_2`	String	Second line of the non-suburb/city/postcode portion of the address.	1703A State Highway 1
`pxid`	String	Unique address identifier.	3-.1.1d.2.42.1T.2
`supplementary`	String	Additional words such as addressee, recipient or building name that are included in the queried address string but are not part of the official verified address. You may wish to save the supplementary value and include it when printing delivery labels.	Jane Smith
`success`	Boolean	Indicates if the request was successful or not.	true
`matched`	Boolean	Indicates if the address has been matched or not.	true

Errors

Below are the possible errors that can be returned by the API.