New Zealand address metadata

The address autocomplete service returns useful information about each address. On selection of an address, the widget can be configured to collect the information documented in the response spec below.

Metadata response specification

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 of the street as supplied by Land Information New Zealand or NZ Post. Note: The street attribute also includes the Street Type.	Pūrākaunui Road
street_name	String	Holds the name of the street as supplied by Land Information New Zealand or NZ Post.	Pūrākaunui
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
street_type	String	The type of street.	Avenue
street_suffix	String	The suffix of the street. Typically contains a compass direction.	North
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.	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
success	Boolean	Indicates if the request was successful or not.	true

Autocomplete parameters (address_params)

This table contains parameters and options that control which addresses are searched and returned for display in the drop down.

Property	Type	Description	Value
delivered	String	Filter to search and return addresses delivered to by NZ Post.
Filter	String	Search and return addresses delivered to by NZ Post.	1
All	String	Omit to search and return postal and non-postal (default).
post_box	String	Filter to includes/excludes PO Box type addresses from the search results.
Exclude		Excludes PO Box type addresses from the search results.	0
Include		Omit to include PO Box type addresses in the search results (default).
rural	String	This filter includes/excludes rural/urban addresses.
Exclude		Excludes rural addresses from the search results.	0
Include		Omit to include rural addresses in the search results (default).
region_code	String	Filter to search addresses located in a single specified region (Regional Authority). See the region codes list here.	Eg. 3
max	Integer	The maximum number of results to return. A number between 1 and 100. (default is 10).	10
ascii	String	Control to reformat special characters (Eg. macrons) with their ASCII equivalent
Reformat		Reformats special characters with their ASCII equivalent.	1
Include		Omit to retain special characters within addresses in the search results (default).

Metadata parameters (address_metadata_params)

This table contains parameters and options that control the source of the address and metadata attributes returned on selection of an address.

Property	Type	Description	Value
census	String	Used to determine which census year’s statistical area identifiers (Meshblock, SA1 & SA2) will be returned in the response.
2018		census (default)	2018
2023		census	2023
ascii	Integer	Control to reformat special characters (Eg. macrons) with their ASCII equivalent
Reformat		Reformats special characters with their ASCII equivalent.	1
Include		Omit to retain special characters within addresses and other fields of the response (default).