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	Default	Description	Test Value
key		Your unique licence key (find on Portal credentials) Required string
secret		Your unique secret key (find on Portal credentials). This required when calling API endpoints without a referer. Optional string
format	json	The required format of the response. Optional string	-- Select --jsonxml
q		The address to be verified. Optional 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. Optional string	-- Select --01
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 Optional string	-- Select --123456789ABCDEFGH
census	2018	Desired data source for Statistics NZ metadata. Optional integer	-- Select --20182023
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. Optional 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). Optional string	-- Select --1

Responses

200 OK

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

400 Bad request

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

See API Error Reference for details.