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 | 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 is required when calling API endpoints without a referer. Optional string | |
format | json | The required format of the response. Optional 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. Optional string | |
dpid | | Unique reference number assigned to a delivery address by NZ Post. You must supply either a pxid or dpid field. Optional string | |
census | 2018 | Desired data source for Statistics NZ metadata. Optional 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. Optional string | |
ascii | | Set to Optional string |
Responses
200 The API response will contain a hash with an element named completions, which is an array of hashes.
| 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. | 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. Note The street attribute also includes the Street Type. | State Highway 1 |
street_name | string | Holds the name of the street. | Queen |
street_type | string | The type of street. | Avenue |
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 meshblock returned is from the 2018 census. | 146004 |
sa1_id | string | Statistical area 1 (2018 census only) | 7000001 |
sa2_id | string | Statistical area 2 ID (2018 census only) | 100200 |
sa2 | string | Statistical area 2 name (2018 census only) | 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 (2018 census only) | Kaimaumau |
ur_id | string | Urban rural ID (2018 census only) | 1002 |
iur | string | Urban rural indicator name (2018 census only) | Rural settlement |
iur_id | string | Urban rural indicator ID (2018 census only) | 21 |
aims_road_section_id | string | The unique road section identifier from Land Information New Zealand (LINZ). | 323309 |
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 (2018 census only) | 4 |
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 (2018 census only) | 48 |
con | string | Constituency name (2018 census only) | Te Hiku Constituency |
con_id | string | Constituency ID (2018 census only) | 65 |
maoricon | string | Maori Constituency name (2018 census only) | Okurei Maori Constituency |
maoricon_id | string | Maori Constituency ID (2018 census only) | 258 |
ward | string | Ward name (2018 census only) | Banks Peninsula Ward |
ward_id | string | Ward ID (2018 census only) | 3086 |
cb | string | Community Board name (2018 census only) | Te Hiku Community |
cb_id | string | Community Board ID (2018 census only) | 65 |
tasub | string | Territorial Authority Subdivision name (2018 census only) | Akaroa Subdivision |
tasub_id | string | Territorial Authority Subdivision ID (2018 census only) | 06019 |
landwater | string | Land/Water description (2018 census only) | Inlet |
landwater_id | string | Land/Water ID (2018 census only) | 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 |
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.