Addressfinder

The best way to find exact addresses in New Zealand

  • Skip to Main Navigation
  • Skip to Footer Sitemap
  • Skip to Top
  • About
    • About Us
    • Case Studies
    • FAQ
    • Partners
    • Blog
    • Contact Us
  • Pricing
  • Industries
    • E-commerce
      Collect verified delivery addresses
    • Finance
      Verified address data for KYC and AML
    • Utilities
      Make network connections faster
  • Features
    • Autocomplete
      Search addresses and locations as you type
    • Bulk Cleansing
      Verify a database of addresses
    • Email Verification
      Collect only valid email addresses
    • Geocode Addresses
      Collect addresses and GPS coordinates together
    • Address Metadata
      Get extra data about addresses
    • MORE FEATURES
  • Address Verification
    • Integration Guide
    • Code Examples
    • API Reference
    • Code Generator
    • Javascript Reference
    • International Integration
  • Email Verification
    • Integration Guide
    • Code Examples
    • API Reference
  • About
    • About us
    • Case Studies
    • Frequently Asked Questions
    • Partners
    • Blog
    • Contact Us
  • Pricing
  • Industries
    • E-commerce
      Collect verified delivery addresses
    • Finance
      Verified address data for KYC and AML
    • Utilities
      Make network connections faster
  • Features
    • Autocomplete
      Search addresses and locations as you type
    • Bulk Cleansing
      Verify a database of addresses
    • Email Verification
      Collect only valid email addresses
    • Geocode Addresses
      Collect addresses and GPS coordinates together
    • Address Metadata
      Get extra data about addresses
    • MORE FEATURES
  • Documentation
    • Integrations
      • Magento
      • WooCommerce
      • Hubspot
      • Salesforce
      • Shopify Plus
      See all integrations
    • Address Verification
      • Integration Guide
      • Code Examples
      • API Reference
      • Code Generator
      • Javascript Reference
      • International Integration
    • Email Verification
      • Integration Guide
      • Code Examples
      • API Reference
  • Login

Address Verification API (NZ)

  • Build
  • Send
  • Response
  • Errors

This page contains the technical information for our Address Verification API. For information about our Bulk Cleansing service, which makes use of this API, please see our Bulk Cleansing page.

The Address Verification API takes an address (potentially containing spelling mistakes and/or other errors) and attempts to match it against a valid address record in the Addressfinder database.

FAQ: How do I get the best results from Address Verification?

Build the request URL

Use the form below to build your request URL from the available parameters. The URL string will be generated and can be sent to the API in order to provide insight into how the API works and the response it returns. Or, if you are using Postman for your investigation, development and testing, include the desired parameters and copy and paste the request URL below into Postman's GET request URL field.

Field Name Value Type Description
String Your unique licence key (find on Portal credentials)
String Your unique secret key (find on Portal credentials). Alternatively, you can pass your secret key into the Authorization header of the request as such: Authorization: your-secret
String The address to be verified.
String The format of the response.
  • Options

    json json for a response in json format.

    xml xml for a response in xml format.

String This filter includes/excludes PO Box style addresses.
  • Options

    Exclude PO Box addresses 0

    PO Box only 1 Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types.

String Will only match and return an address if exists within the selected region (Regional Authority).

Including a region can improve your match success rate as it removes the possibility of matching addresses outside the selected region.
  • Options

    Auckland 1

    Bay of Plenty 2

    Canterbury 3

    Gisborne 4

    Hawke's Bay 5

    Manawatu-Wanganui 6

    Marlborough 7

    Nelson 8

    Northland 9

    Otago A

    Southland B

    Taranaki C

    Tasman D

    Waikato E

    Wellington F

    West Coast G

    Chatham Islands H

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

https://api.addressfinder.io/api/nz/address/verification/
      
        /* Click the button above to see a real API response here */
        {
          "success": true
        }
      
    

Response Specification

The API response will include all the attributes associated with the matched address in the format requested in the API request. Empty attributes for the matched address will not be returned in the response.

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 and type of the street. Pūrākaunui Road
street_name
String Holds the full name of the street. Pūrākaunui
street_type
String The type of street. avenue
street_suffix
String The suffix of the street. Typically contains a compass direction. North
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
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. If a value is present, then this address can be delivered to 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
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
matched
Boolean Indicates if the address has been matched or not. true

Errors

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

  • Validation error (1000)
  • Key not found (1001)
  • Key not provided (1002)
  • Domain not registered with Addressfinder (1003)
  • Secret not provided (1004)
  • Direct API calls are not permitted on your current plan. (1005)
  • Invalid credentials (1006)
  • Secret should not be supplied (1008)
  • The Addressfinder plugin has exceeded the number of allowed lookups, and is now suspended (1009)
  • The record you are trying to load does not exist (1011)
  • Domain parameter must not be included in a web request (1015)
  • This domain has been blocked (1016)
  • This service is not enabled on your current plan (1017)
  • Your IP address has been blocked for these credentials (1018)
  • HTTP Referer or Origin header record must be present when making a browser initiated request (1019)
  • Your Addressfinder trial has ended (1020)
  • Your Addressfinder trial has exceeded its allowed lookups (1021)
  • Postal addresses are not enabled on your current plan (1022)
  • Address Verification Widget
    • Integration guide
    • Widget code generator
    • Code examples
    • Best practices
    • Fixing browser quirks
    • Advanced usage
    • Can't find your address?
    • JavaScript widget reference
  • Email Verification
    • Email Verification API
    • Widget integration guide
    • Widget advanced usage
  • API Documentation (NZ)
    • Address Autocomplete
    • Address Metadata
    • Address Verification
    • Address Reverse Geocode
    • Location Autocomplete
    • Location Metadata
    • Points of Interest Autocomplete
    • Points of Interest Metadata
    • API Errors
  • API Documentation (AU)
    • Address Autocomplete
    • Address Metadata
    • Address Verification
    • Location Autocomplete
    • Location Metadata
    • API Errors
  • API Documentation (INT'L)
    • Address Autocomplete
    • Address Metadata
  • Integrations
    • Magento
    • WooCommerce
    • BigCommerce
    • Salesforce
    • Shopify Plus
    • Hubspot
    • StoreConnect
    • Spiffy Stores
    • Ruby
    • iOS
    • Drupal
    • Microsoft Dynamics 365
    • Vue
    • Gravity Forms
    • React
Addressfinder logo
Addressfinder provides speedy, accurate and dependable address autocompletion at a fair price. Easily integrate our address finder software with your site to start enjoying our address verification, address autocomplete and other address services today.

Sitemap

  • About
  • About Us
  • Contact
  • Blog
  • FAQ
  • Pricing
  • Case Studies
  • Status Page
  • Privacy Policy
  • Terms & Conditions
  • Features
  • Address Autocomplete
  • Address Metadata
  • Bulk Address Cleansing
  • Address Geocoding
  • Email Address Verification
  • Reverse Address Lookup
  • Points of Interest
  • Street, Suburb & City Search
  • Postcode Finder
  • Address Verification
  • Integrations
  • WooCommerce
  • BigCommerce
  • Shopify Plus
  • Magento
  • Salesforce
  • Spiffy Stores
  • iOS
  • Ruby
  • HubSpot
  • StoreConnect
  • Drupal
  • Microsoft Dynamics 365
  • Vue
  • Gravity Forms
  • React
  • API Documentation
  • Address Autocomplete
  • Address Metadata
  • Address Verification
  • Email Verification
  • API Errors
  • AU APIs specs
  • International APIs
  • Widget Documentation
  • Integration Guide
  • Code Generator
  • Code Examples
  • Javascript Reference
  • International Integration Guide
  • Email Integration Guide
Addressfinder is also available in Australia
Terms and Conditions | Privacy
Copyright © 2023 Addressfinder, New Zealand