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

Location Autocomplete API (NZ)

  • Build
  • Send
  • Response
  • Errors

This API lets you search for streets, suburbs, cities and/or regions (we call these locations).

The filters below are applied additively, so if you need to return multiple location types, you should exclude those location types that are not required.

For example, to search for suburbs and cities apply filters of streets=0 and regions=0

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 query string to be matched with the location.
String The required format of the response.
  • Options

    json json for a response in json format.

    xml xml for a response in xml format.

String This filter restricts results to streets
  • Options

    not street 0 Return everything other than streets

    street 1 Return only streets

String This filter restricts results to suburbs.
  • Options

    not suburb 0 Return everything other than suburbs

    suburb 1 Return only suburbs

String This filter restricts results to cities.
  • Options

    not city 0 Return everything other than cities.

    city 1 Return only cities

String This filter restricts results to regions.
  • Options

    not region 0 Return everything other than regions

    region 1 Return only regions

String Only return locations within the boundary of the selected region (Regional Authority).
  • 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

String Determines how closely matched the results should be to the q parameter.
  • Options

    Normal search 0 Allows some address elements to be omitted but does not allow spelling errors.

    Strict search 1 Requires all address elements entered in q to be ordered and spelt correctly.

    Fuzzy search 2 Allows spelling errors and inaccurate address elements.

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
Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.
Integer Returns an additional attribute in the response called highlighted_a. This attribute wraps the matching terms in the address with <span class='af_hl'></span> in order to highlight those terms.
  • Options

    Highlighted 1

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

Request URL

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

Response Specification

The API response will contain a hash with an element named completions, which is an array of hashes containing the following fields.

Field Name Type Description Example
a
String Canonical location as supplied by Land Information New Zealand. Willcox Grove, Naenae, Lower Hutt
pxid
String The unique location identifier. 1-.F.b.M.1C
success
Boolean Indicates if the request was successful 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