AddressFinder

The best way to find exact addresses in New Zealand

  • Skip to Main Navigation
  • Skip to Footer Sitemap
  • Skip to Top

Menu

Get Started Free

  • Pricing
  • Features & plugins
  • About us
  • Case studies
  • FAQ
  • Contact
  • Blog
  • JavaScript widget docs
  • API developer docs
  • Log in
  • Pricing
  • Features
  • More
    • Company & product
      • About Us
      • Case Studies
      • FAQ
      • Partners
      • Blog
      Contact Us
    • Plugins
      • Magento
      • WooCommerce
      • BigCommerce
      • Salesforce
      • Shopify
      • iOS
    • JavaScript widget docs
      • Integration Guide
      • Widget Code Generator
      • Code Examples
      • Widget Reference
      See all JavaScript docs
    • API developer docs
      • Address Autocomplete
      • Address Metadata
      • Address Verification
      See all API docs
  • Log in
  • Get Started Free

Address Metadata API (NZ)

  • Build
  • Send
  • Response
  • Errors

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

Build the request URL

Use the form below to build your request URL from the parameters. A URL string will be generated from these parameters and sent to the API in order to provide insight into how the API works and the responses it returns.

Field Name Value Type Description
String Your unique licence key (find on Portal overview page)
String Your unique secret key (find on Portal overview page)
String The format of the response.
  • Options

String Unique address id obtained from the Address Autocomplete or Bounding Box APIs.

You must supply either a pxid or dpid field.
Integer Unique reference number assigned to a delivery address by NZ Post.

You must supply either a pxid or dpid field.
Integer Desired data source for Statistics NZ metadata.
  • Options

String Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. FAQ: learn more about the domain parameter

* Parameters marked with an asterisk are mandatory for this API call.

Request URL

      
  /* Click the button above to see a real API response here */
  {
    "success": true
  }
      
    

Response Specification

The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request.

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. Note: The street attribute also includes the Street Type. State Highway 1
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
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
pxid * String Unique address identifier. 3-.1.1d.2.42.1T.2
dpid String A unique reference number assigned to each delivery address by NZ Post. 2668726
aims_address_id String The unique identifier from Land Information New Zealand (LINZ). 1518959
aims_road_section_id String The unique road section identifier from Land Information New Zealand (LINZ). 323309
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 2013 census. The default data source will change to the 2018 census in June 2019. 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
ur_id String Urban rural ID (2018 census only) 1002
ur String Urban rural name (2018 census only) Kaimaumau
iur_id String Urban rural indicator ID (2018 census only) 21
iur String Urban rural indicator name (2018 census only) Rural settlement
cb_id String Community Board ID (2018 census only) 00101
cb String Community Board name (2018 census only) Te Hiku Community
con_id String Constituency ID (2018 census only) 0101
con String Constituency name (2018 census only) Te Hiku Constituency
maoricon_id String Maori Constituency ID (2018 census only) 0402
maoricon String Maori Constituency name (2018 census only) Okurei Maori Constituency
region_id String Region ID (2018 census only) 04
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
ta_id String Territorial Authority ID (2018 census only) 060
ta * String The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. Auckland
tasub_id String Territorial Authority Subdivision ID (2018 census only) 06019
tasub String Territorial Authority Subdivision name (2018 census only) Akaroa Subdivision
ward_id String Ward ID (2018 census only) 06016
ward String Ward name (2018 census only) Banks Peninsula Ward
landwater_id String Land/Water ID (2018 census only) 22
landwater String Land/Water description (2018 census only) Inlet
success * Boolean Indicates if the request was successful or not. true

* Attributes marked with an asterisk will always be present in a successful API response.

Errors

Below are the possible errors that can be returned by the API.

Code Error Cause Resolution
1000
Validation error Returned when one of the supplied parameters is missing or incorrect. The response will contain a message attribute which explains the cause of the validation error. An example JSON response is shown below for a request which failed to include the q parameter. {
completions: [ ],
message: 'Q can not be blank',
error_code: '1000'
}
Check that the supplied parameters contain valid values, and that the mandatory parameters have been included.
1001
Account key not found Returned when the key included in your API call cannot be found in our database. This will normally happen when you make a copy ’n paste error. Compare the key included in your API call with the key listed in the AddressFinder Portal overview page.

Also confirm there are no additional spaces or characters in your API call.
1002
Account key is missing Returned when you fail to send through your key with each request. The key is a mandatory parameter. Check that you are using the correct parameter name key.
1003
Invalid domain Returned when you embed AddressFinder on a website that differs from the domain that you specified in the AddressFinder Portal. The AddressFinder Portal records the whitelist of allowed domains for your account.

Login to the AddressFinder Portal and add the domain of this website to your account.
1004
Account secret missing Returned when you fail to send through your secret with an API call.

Can also occur when using the widget and the HTTP Referer header is not included.
Include the secret listed in the AddressFinder Portal overview page in your API call.

When using the widget, you must load the page from a web server (e.g. localhost) and not a file:// scheme.
1005
API calls require a Paid plan. Returned if you try to call the API and you are on a Free plan. Free accounts are expected to use the JavaScript Widget only. Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan.

A Developer plan is available for customers in development. Contact us to request the necessary plan change
1006
Invalid secret value Returned when the supplied secret value does not match the value stored in our database. This will normally happen when you make a copy ’n paste error. Compare the secret included in your API call with the secret listed in the AddressFinder Portal overview page.

Also confirm there are no additional spaces or characters in your API call.
1008
Secret should not be supplied This is a safety check to ensure that the secret parameter has not been included when making requests from your web browser. You should never include the secret on any web page. The secret should be used for server-to-server API calls only.
1009
Account has been suspended Returned when your account (Free plans only) has hit its 100% usage limit for the billing period. Visit the AddressFinder Portal and upgrade your account to a Paid plan.

Alternatively wait until the end of the month when suspended accounts are automatically reactivated.
1011
Record not found Returned when the supplied address identifier cannot be found. This can happen when a stale identifier is included in the API call. Do not save address identifiers in your database, as they are transisent and may change after each database update.
1014
Account Disabled Your account has been disabled by AddressFinder support. Contact AddressFinder support to reactivate your account.
1015
Cannot include domain parameter in a web request You have included a domain parameter in your browser based API call. Remove the domain parameter from your API call.
1017
This activity is not permitted on your current plan You have attempted to use an AddressFinder service that is not valid for current plan. Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan.

Alternatively Contact us to discuss plan options.
  • JavaScript Widget
    • Integration guide
    • Widget code generator
    • Code examples
    • Best practices
    • Fixing browser quirks
    • Advanced usage
    • Can't find your address?
    • JavaScript widget reference
  • API Specs (NZ)
    • Address Autocomplete
    • Address Metadata
    • Address Verification
    • Address Reverse Geocode
    • Address Bounding Box
    • Location Autocomplete
    • Location Metadata
    • Points of Interest Autocomplete
    • Points of Interest Metadata
  • API Specs (AU)
  • Integrations
    • Magento
    • WooCommerce
    • BigCommerce
    • Salesforce
    • Shopify
    • Spiffy Stores
    • Ruby
    • iOS

Sitemap

Home

  • About
  • Contact
  • Blog
  • FAQ
  • Pricing
  • Case Studies
  • Status Page
  • Privacy Policy
  • Terms & Conditions

Features

  • Address Autocomplete
  • Address Verification
  • Address Metadata
  • Geocode Addresses
  • Reverse Geocode Addresses
  • Points of Interest
  • Street, Suburb & City Search
  • Bounding Box Search
  • Customer Portal

Plugins

  • WooCommerce
  • BigCommerce
  • Shopify
  • Magento
  • Salesforce
  • Spiffy Stores
  • iOS
  • Ruby

API Documentation

  • Address Autocomplete
  • Address Metadata
  • Address Verification
  • API Errors
  • Another 6 APIs
  • AU APIs specs

Widget Documentation

  • Integration Guide
  • Code Generator
  • Code Examples
  • Javascript Reference

Get Started Free

AddressFinder is also available in Australia