AddressFinder

The best way to find exact addresses in Australia

  • 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
    • Integrations
      • Magento
      • WooCommerce
      • BigCommerce
      • Salesforce
      • Shopify Plus
      See all integrations
    • JavaScript widget docs
      • Integration Guide
      • Widget Code Generator
      • Widget Reference
      • Code Examples
      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

    json json for a response in json format.

    xml xml for a response in xml format.

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

    2013 2013 census

    2018 2018 census (default)

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_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 Census parameter will default to 2018. 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) 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 (2018 census only) 060
con
String Constituency name (2018 census only) Te Hiku Constituency
con_id
String Constituency ID (2018 census only) 0101
maoricon
String Maori Constituency name (2018 census only) Okurei Maori Constituency
maoricon_id
String Maori Constituency ID (2018 census only) 0402
ward
String Ward name (2018 census only) Banks Peninsula Ward
ward_id
String Ward ID (2018 census only) 06016
cb
String Community Board name (2018 census only) Te Hiku Community
cb_id
String Community Board ID (2018 census only) 00101
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

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
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
Key not provided 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
Domain not registered with AddressFinder 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 domains that are allowed to use your account.

Login to the AddressFinder Portal and add the domain of this website to your account.
1004
Secret not provided 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
Direct API calls are not permitted on your current plan. Returned if you try to call the API and you are on either a Free or Agile plan. These plan types provide access to the JavaScript Widget and plugins only. Upgrade to a Business plan. Visit the AddressFinder Portal to change plan.
1006
Invalid credentials Returned when the supplied key and/or secret value are incorrect. This will normally happen when you make a copy ’n paste error. Compare the key and secret included in your API call with the values listed on the AddressFinder Portal credentials 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
The AddressFinder plugin has exceeded the number of allowed lookups, and is now suspended Returned when your account (free plans only) has hit its 100% usage limit for the billing period. Visit the AddressFinder Portal and switch to a Paid plan.

Alternatively wait until the end of the month when suspended accounts are automatically reactivated.
1010
Account not authorised to use this API Returned when you make an API call that you are not permitted to use Contact AddressFinder support to request access to this API.
1011
The record you are trying to load does not exist 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 transient and may change after each database update.
1012
Account not authorised to use this API Returned when you make an API call that you are not permitted to use Contact AddressFinder support to request access to this API.
1013
This API has been discontinued This API has been discontinued Contact AddressFinder support to discuss alternatives.
1014
Account Disabled Your account has been disabled by AddressFinder support. Contact AddressFinder support to discuss reactivating your account.
1015
Domain parameter must not be included in a web request You have included a domain parameter in your browser based API call. The domain parameter is for direct API calls only. Remove the domain parameter from your web request.
1016
This domain has been blocked These credentials are not permitted to be used on this domain. Contact AddressFinder support to discuss removing the block.
1017
This service is not enabled on your current plan You have attempted to use an AddressFinder service that is not enabled on your current plan. Visit the AddressFinder Portal to change plan.
1018
Your IP address has been blocked for these credentials This service has been configured to only allow access from defined IP addresses. Visit the AddressFinder Portal and add your IP address to the IP Allow List.
1019
HTTP Referer or Origin header record must be present when making a browser initiated request You have attempted to use the AddressFinder widget from a browser that does not include the referrer or orgin headers along with each request. Confirm that this request was sent from a valid web server (not the local filesystem), and that you do not have browser plugins interfering with the request.
1020
Your AddressFinder trial has ended Returned when the trial term has ended. Log into the AddressFinder Portal and upgrade your account to a suitable plan.
1021
Your AddressFinder trial has exceeded its allowed lookups. Returned when you have exceeded the number of lookups permitted on the trial plan. Log into the AddressFinder Portal and upgrade your account to a suitable plan.
  • JavaScript Widget
    • Integration guide
    • Widget code generator
    • Code examples
    • Best practices
    • Fixing browser quirks
    • Advanced usage
    • JavaScript widget reference
  • API Specs (AU)
    • Address Autocomplete
    • Address Metadata
    • Address Verification
    • Location Autocomplete
    • Location Metadata
    • API Errors
  • API Specs (NZ)
  • Integrations
    • Magento
    • WooCommerce
    • BigCommerce
    • Salesforce
    • Shopify Plus
    • Spiffy Stores
    • Ruby
    • iOS
    • Drupal
    • Microsoft Dynamics 365
    • Vue
    • Gravity Forms

Sitemap

Home

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

Features

  • Australian Address Autocomplete
  • Australian Address Verification
  • Australian Address Metadata
  • Geocode Australian Addresses
  • Street, Suburb & City Search
  • Customer Portal

Integrations

  • WooCommerce
  • BigCommerce
  • Shopify Plus
  • Magento
  • Salesforce
  • Spiffy Stores
  • iOS
  • Ruby
  • Drupal
  • Microsoft Dynamics 365
  • Vue
  • Gravity Forms

API Documentation

  • Address Autocomplete
  • Address Metadata
  • Address Verification
  • API Errors
  • Another 2 APIs
  • NZ API specs

Widget Documentation

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

Get Started Free

AddressFinder is also available in New Zealand