Address Metadata API

The Address Metadata API is used to collect the metadata associated with an address selected from the Address Autocomplete API

Endpoint

New Zealand

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

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`
`pxid`	Unique address identifier obtained from the NZ Address Autocomplete or NZ Address Bounding Box APIs. You must supply either a pxid or dpid field. Type: `string`
`dpid`	Unique reference number assigned to a delivery address by NZ Post. You must supply either a pxid or dpid field. 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 The API response will contain a hash with an element named completions, which is an array of hashes.

Name	Description	Example
`a`	Canonical address as supplied by Land Information New Zealand or NZ Post. Type: `string`	Unit 2, 1703A State Highway 1, Warkworth 0983
`postal`	Associated postal address when supplied by NZ Post. Field will be omitted if this address is not delivered to by NZ Post. Type: `string`	Unit 2, 1703A State Highway 1, RD 3, Warkworth 0983
`building_name`	Holds the building or property name. Type: `string`	Miban Building
`unit_type`	Describes the category of a sub-dwelling. Type: `string`	Flat
`unit_identifier`	Identifies a specific sub dwelling. Can be alpha, number or a combination. Type: `string`	1
`floor`	The level number and level type in a multi-story building. Type: `string`	Level 19
`number`	The street number of the address. Also populated with the box number for PO Box type addresses. Type: `string`	1703
`alpha`	Holds the alpha component of a street number. In the address 1B High Street, B is the alpha. Type: `string`	B
`street`	Holds the full name of the street. Note The street attribute also includes the Street Type. Type: `string`	State Highway 1
`street_name`	Holds the name of the street. Type: `string`	Queen
`post_street`	Holds the street name and type from NZ Post, it will be omitted if the address is not delivered to by NZ Post. Type: `string`	Purakaunui Road
`post_street_name`	Holds the street name from NZ Post, it will be omitted if the address is not delivered to by NZ Post. Type: `string`	Purakaunui
`street_type`	The type of street. Type: `string`	Avenue
`suburb`	The suburb or locality of the address as assigned by Land Information New Zealand. Type: `string`	Warkworth
`city`	The city, town or locality name as assigned by Land Information New Zealand. Type: `string`	Warkworth
`box_type`	The type of PO Box/CMB/Private Bag/Counter Delivery. Type: `string`	PO Box
`lobby_name`	The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located. Type: `string`	Fendalton
`rd_number`	The rural delivery number assigned by NZ Post to a rural address. Type: `string`	4
`post_suburb`	Name of the suburb when supplied by NZ Post. Type: `string`	Manukau
`mailtown`	Name of the town/city when supplied by NZ Post. Type: `string`	Warkworth
`postcode`	Holds the four digit postcode. Type: `string`	0983
`dpid`	A unique reference number assigned to each delivery address by NZ Post. Type: `string`	2668726
`primary_parcel_id`	The unique identifier of the portion of land associated with the selected address. Type: `string`	3866475
`aims_address_id`	The unique identifier from Land Information New Zealand (LINZ). Type: `string`	1518959
`x`	Longitude coordinate (in WGS84 format). Type: `string`	174.643199
`y`	Latitude coordinate (in WGS84 format). Type: `string`	-36.426956
`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`	146004
`sa1_id`	Statistical area 1 (2018 census only) Type: `string`	7000001
`sa2_id`	Statistical area 2 ID (2018 census only) Type: `string`	100200
`sa2`	Statistical area 2 name (2018 census only) Type: `string`	Rangaunu Harbour
`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`	true
`ur`	Urban rural name (2018 census only) Type: `string`	Kaimaumau
`ur_id`	Urban rural ID (2018 census only) Type: `string`	1002
`iur`	Urban rural indicator name (2018 census only) Type: `string`	Rural settlement
`iur_id`	Urban rural indicator ID (2018 census only) Type: `string`	21
`aims_road_section_id`	The unique road section identifier from Land Information New Zealand (LINZ). Type: `string`	323309
`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
`region`	The Regional Authority in which this address exists. Note Regional Authorities are the top tier of local government in New Zealand. Type: `string`	Auckland Region
`region_id`	Region ID (2018 census only) Type: `string`	4
`ta`	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. Type: `string`	Auckland
`ta_id`	Territorial Authority ID (2018 census only) Type: `string`	48
`sufi`	Same as `aims_address_id`, returned as integer. Type: `integer`	1518959
`con`	Constituency name (2018 census only) Type: `string`	Te Hiku Constituency
`con_id`	Constituency ID (2018 census only) Type: `string`	65
`maoricon`	Maori Constituency name (2018 census only) Type: `string`	Okurei Maori Constituency
`maoricon_id`	Maori Constituency ID (2018 census only) Type: `string`	258
`ward`	Ward name (2018 census only) Type: `string`	Banks Peninsula Ward
`ward_id`	Ward ID (2018 census only) Type: `string`	3086
`cb`	Community Board name (2018 census only) Type: `string`	Te Hiku Community
`cb_id`	Community Board ID (2018 census only) Type: `string`	65
`tasub`	Territorial Authority Subdivision name (2018 census only) Type: `string`	Akaroa Subdivision
`tasub_id`	Territorial Authority Subdivision ID (2018 census only) Type: `string`	06019
`landwater`	Land/Water description (2018 census only) Type: `string`	Inlet
`landwater_id`	Land/Water ID (2018 census only) Type: `string`	22
`address_line_1`	First line of the non-suburb/city/postcode portion of the address Type: `string`	Unit 2
`address_line_2`	Second line of the non-suburb/city/postcode portion of the address. Type: `string`	1703A State Highway 1
`pxid`	Unique address identifier. Type: `string`	3-.1.1d.2.42.1T.2
`success`	Indicates if the request was successful 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.