Address Verification API

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.

Endpoint

New Zealand

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

Parameters

Parameter	Description	Test Value
`key`	Your unique licence key (find on Portal credentials) Type: `string` `required`
`secret`	Your unique secret key from Portal Credentials. You can also pass your secret key into the `Authorization` header of the request. Only required for server-to-server calls. Type: `string`
`format`	The required format of the response. Default value: `json` Type: `string`
`q`	The address to be verified. Type: `string`
`post_box`	This filter includes/excludes PO Box style addresses. `0` - Excludes PO Box type addresses from being returned in the response. `1` - Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types. Omit to not filter. Returns PO Box type and standard addresses in the response. Type: `string`
`region_code`	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. `1` - Only returns addresses from the Auckland Region `2` - Only returns addresses from the Bay of Plenty Region `3` - Only returns addresses from the Canterbury Region `4` - Only returns addresses from the Gisbourne Region `5` - Only returns addresses from the Hawke's Bay Region `6` - Only returns addresses from the Manawatu-Wanganui Region `7` - Only returns addresses from the Marlborough Region `8` - Only returns addresses from the Nelson Region `9` - Only returns addresses from the Northland Region `A` - Only returns addresses from the Otago Region `B` - Only returns addresses from the Southland Region `C` - Only returns addresses from the Taranaki Region `D` - Only returns addresses from the Tasman Region `E` - Only returns addresses from the Waikato Region `F` - Only returns addresses from the Wellington Region `G` - Only returns addresses from the West Coast Region `H` - Only returns addresses from the Chatham Islands Region Omit to not filter. Returns addresses from all Regions Type: `string`
`census`	Desired data source for Statistics NZ metadata. Default value: `2018` Type: `integer`
`domain`	Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. Type: `string`
`ascii`	Set to `1` to reformat special characters like macrons and other accents characters with their ASCII equivalent (e.g. Pōneke and Café will be returned as Poneke and Cafe). Type: `string`

Responses

200 OK

Name	Description	Example
`pxid`	Unique address identifier. Type: `string`	2-2eNwG1oBJExni2nUFJm1cW
`a`	Canonical address as supplied by Land Information New Zealand or NZ Post. Type: `string`	1 Ghuznee Street, Te Aro, Wellington 6011
`aims_address_id`	The unique identifier from Land Information New Zealand (LINZ). Type: `string`	2122864
`ta_id`	Territorial Authority ID (2018 census only) Type: `string`	047
`ta`	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. Type: `string`	Wellington City
`tasub_id`	Territorial Authority Subdivision ID (2018 census only) Type: `string`	04799
`tasub`	Territorial Authority Subdivision name (2018 census only) Type: `string`	Area Outside Subdivision
`number`	The street number of the address. Also populated with the box number for PO Box type addresses. Type: `string`	1
`x`	Longitude coordinate (in WGS84 format). Type: `string`	174.777711971851
`y`	Latitude coordinate (in WGS84 format). Type: `string`	-41.2940464548652
`postcode`	Holds the four digit postcode. Type: `string`	6011
`street`	Holds the full name of the street. Note The street attribute also includes the Street Type. Type: `string`	Ghuznee Street
`street_name`	Holds the name of the street. Type: `string`	Ghuznee
`street_type`	The type of street. Type: `string`	street
`city`	The city, town or locality name as assigned by Land Information New Zealand. Type: `string`	Wellington
`suburb`	The suburb or locality of the address as assigned by Land Information New Zealand. Type: `string`	Te Aro
`region_id`	Region ID (2018 census only) Type: `string`	09
`region`	The Regional Authority in which this address exists. Note Regional Authorities are the top tier of local government in New Zealand. Type: `string`	Wellington Region
`postal_line_1`	Postal address line 1 Type: `string`	1 Ghuznee Street
`postal_line_2`	Postal address line 2 Type: `string`	Te Aro
`postal_line_3`	Postal address line 3 Type: `string`	Wellington 6011
`rural`	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. Type: `boolean`	false
`address_line_1`	First line of the non-suburb/city/postcode portion of the address Type: `string`	1 Ghuznee Street
`primary_parcel_id`	The unique identifier of the portion of land associated with the selected address. Type: `string`	4025566
`meshblock`	The meshblock identifier for the requested census dataset (see census parameter). If not specified, the meshblock returned is from the 2018 census. Type: `string`	2133700
`sa1_id`	Statistical area 1 (2018 census only) Type: `string`	7021601
`sa2_id`	Statistical area 2 ID (2018 census only) Type: `string`	251700
`sa2`	Statistical area 2 name (2018 census only) Type: `string`	Vivian West
`cb_id`	Community Board ID (2018 census only) Type: `string`	04799
`cb`	Community Board name (2018 census only) Type: `string`	Area Outside Community
`ward_id`	Ward ID (2018 census only) Type: `string`	04703
`ward`	Ward name (2018 census only) Type: `string`	Lambton Ward
`con_id`	Constituency ID (2018 census only) Type: `string`	0905
`con`	Constituency name (2018 census only) Type: `string`	Wellington Constituency
`maoricon_id`	Maori Constituency ID (2018 census only) Type: `string`	0999
`maoricon`	Maori Constituency name (2018 census only) Type: `string`	Area Outside Maori Constituency
`iur_id`	Urban rural indicator ID (2018 census only) Type: `string`	11
`iur`	Urban rural indicator name (2018 census only) Type: `string`	major urban area
`ur_id`	Urban rural ID (2018 census only) Type: `string`	1402
`ur`	Urban rural name (2018 census only) Type: `string`	Wellington
`landwater_id`	Land/Water ID (2018 census only) Type: `string`	12
`landwater`	Land/Water description (2018 census only) Type: `string`	Mainland
`supplementary`	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. Type: `string`	Jane Smith
`success`	Indicates if the request was successful or not. Type: `boolean`	true
`matched`	Indicates if the address has been matched or not. Type: `boolean`	true

400 Bad request

Name	Description	Example
`completions`	An empty array will be returned due to the error Type: `array`	-
`error_code`	A unique numerical value identifying the error that occured Type: `string`	1004
`message`	An informative message describing the error that occured Type: `string`	Secret not provided
`success`	Indicates if the request was successful or not Type: `boolean`	false

See API Error Reference for details.