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
    • Address Autocomplete
      Search verified addresses as you type
    • Bulk Cleansing
      Verify your database of addresses and emails
    • Email Verification
      Collect only valid email addresses
    • Phone Verification
      Verify numbers at the point of collection
    • Geocode Addresses
      Collect addresses and GPS coordinates together
    • Address Metadata
      Get extra data about addresses
    • MORE FEATURES
  • Address Verification
    • Integration Guide
    • Javascript Reference
    • Code Examples
    • API Reference
    • Code Generator
    • International Integration
  • Email Verification
    • Integration Guide
    • Javascript Reference
    • Code Examples
    • API Reference
  • Phone Verification
    • Integration Guide
    • Javascript Reference
    • 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
    • Address Autocomplete
      Search verified addresses as you type
    • Bulk Cleansing
      Verify your database of addresses and emails
    • Email Verification
      Collect only valid email addresses
    • Phone Verification
      Verify numbers at the point of collection
    • 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
      • Javascript Reference
      • Code Examples
      • API Reference
      • Code Generator
      • International Integration
    • Email Verification
      • Integration Guide
      • Javascript Reference
      • Code Examples
      • API Reference
    • Phone Verification
      • Integration Guide
      • Javascript Reference
      • Code Examples
      • API Reference
  • Login

Javascript Widget Reference NZ

AddressFinder.Widget class

Constructor

Constructor Parameters Description
AddressFinder.Widget() input:Element, api_key:String, country_code:String, options?:Object Attaches a new widget to the specified input element.

Methods

Method Parameters Return Value Description
on() event_name:String, callback:Function AddressFinder.Widget Subscribes to a specified event.
trigger() event_name:String, arguments…> AddressFinder.Widget Manually fires a specified event.
setOption() option_name:String, value:* AddressFinder.Widget Sets an option after the widget has been initialised.
setCountry() country_code:String AddressFinder.Widget Sets a country after the widget has been initialised.
getOption() option_name:String AddressFinder.Widget Gets the current value of the specified option.
addService() name:String, search_function:Function AddressFinder.Service Function to add an additional third-party search.
disable() AddressFinder.Widget Disables the AddressFinder widget. The autocomplete function will stop operating until it is re-enabled.
enable() AddressFinder.Widget Re-enables a disabled AddressFinder widget.

Options

Option Type Default Description
address_params Object {strict: "2"} Additional parameters to filter the address results. NZ Address params, AU Address params and International Address params. The Code Examples page has some good examples.
address_metadata_params Object nil Additional parameters to adjust the values returned with address metadata. NZ Address Metadata params, AU Address Metadata params, International Address Metadata params.
base_url String https://api.addressfinder.io The base URL endpoint for API calls and CSS resources.
canonical Boolean true Force the selection of the canonical address when an aliased address is selected.
container Object document.body The element that wraps in input field that AddressFinder will use. This is useful when embedding the widget within a scrolling panel. The Code Demos page has some good examples.
empty_class String 'af_empty' CSS class name to be applied to the li element containing the empty_content message.
empty_content String No addresses were found. This could be a new address, or you may need to check the spelling. Learn more Message to display to users when there are no found addresses or locations.
footer_class String 'af_footer' CSS class name to be applied to the li element containing the footer.
hover_class String 'af_hover' CSS class name to be applied to the li element of a highlighted result.
ignore_returns Boolean true Ignore the use of the enter key when no list item is selected.
item_class String 'af_item' CSS class name to be applied to the li element of a result.
list_class String 'af_list' CSS class name to be applied to the ul element containing the results.
location_params Object {} Additional parameters to filter the location results. Add any of the Location Params. The Code Demos page has some good examples.
manual_style Boolean false If true, the widget will not embed the default stylesheet, allowing a custom stylesheet to be used.
(Can only be set when widget is constructed).
max_results Integer 10 Maximum number of results to display.
position String 'absolute' Use a different positioning value for the list_class element. When embedding AddressFinder within a fixed position element, using a matching fixed position value will ensure the popup list appears below the input element.
show_addresses Boolean true Set to false to hide address results.
show_locations Boolean false Set to true to return location (street, suburb, city and region) results.
show_nearby Boolean false Enable the nearby address helper (uses device's GPS to suggest addresses at current location). This feature is only available for New Zealand addresses.
show_points_of_interest Boolean false Set to true to return points of interest (e.g. hospitals, schools and churches) results. This feature is only available for New Zealand addresses.
points_of_interest_params Object {} Additional parameters to filter the points of interest results. Add any of the Points of Interest Params. This feature is only available for New Zealand addresses.

Events

Event Callback Arguments Description
"result:select" selectedAddress:String, metadata:Object Fired when any result is selected. The metadata value returned depends on the type of address selected, which depends on the search criteria supplied. The metadata could be either Australian Address metadata, Australian Location metadata, New Zealand Address metadata, New Zealand Location metadata or New Zealand Point of Interest metadata
"address:select" selectedAddress:String, metadata:Object Just like "result:select", but only fired when an address is selected. The metadata could be either Australian Address metadata or New Zealand Address metadata
"address:select:pre" selectedAddress:String, metadata:Object Fired immediately when an address is selected, before an info request for extended data is made.
"location:select" selectedLocation:String, metadata:Object Just like "result:select", but only fired when a location is selected. The metadata could be either Australian Location metadata or New Zealand Location metadata
"location:select:pre" selectedLocation:String, metadata:Object Fired immediately when an location is selected, before an info request for extended data is made.
"points_of_interest:select" selectedPointOfInterest:String, metadata:Object Just like "result:select", but only fired when a point of interest is selected. The metadata will be New Zealand Point of Interest metadata
"points_of_interest:select:pre" selectedPointOfInterest:String, metadata:Object Fired immediately when an point of interest is selected, before an info request for extended data is made.
"results:update" Fired when all services have updated their results.
"results:empty" Fired when there are no results to display.

AddressFinder.Service class

Constuctor

AddressFinder.Service is returned from the AddressFinder.Widget#addService method.

Methods

Method Parameters Return Value Description
on() event_name:String, callback:Function AddressFinder.Service Subscribes an a specified event.
trigger() event_name:String, arguments… AddressFinder.Service Manually fires a specified event.
setOption() option_name:String, value:* AddressFinder.Service Sets an option after the widget has been initialised.
getOption() option_name:String AddressFinder.Service Gets the current value of the specified option.

Options

Option Type Default Description
renderer Function Allows a function to be defined to format how the result will be displayed. The function will be passed two arguments, the value and the data, and must return a string.

Events

Event Callback Arguments Description
"result:select" selectedAddress:String, metadata:Object Fired when a result from this service is selected.

Address Params

Property Type Description
delivered String This filter determines if the results are either delivered or not delivered by NZ Post.
post_box String This filter includes/excludes PO Box style addresses.
rural String This filter includes/excludes rural/urban addresses.
region_code String Only return addresses within the boundary of the selected region (Regional Authority).
max Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.

Address Metadata Params

Property Type Description Default value
census Integer Desired data source for Statistics NZ census related metadata.
2018 census (default) 2018
2023 census 2023

Address metadata

Property 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 as supplied by Land Information New Zealand or NZ Post. Note: The street attribute also includes the Street Type. Pūrākaunui Road
street_name
String Holds the name of the street as supplied by Land Information New Zealand or NZ Post. Pūrākaunui
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
street_type
String The type of street. Avenue
street_suffix
String The suffix of the street. Typically contains a compass direction. North
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 The Statistical Area 1 identifier for the requested census dataset (see census parameter). If not specified, the census parameter will default to 2018. 7000001
sa2_id
String The Statistical Area 2 identifier for the requested census dataset (see census parameter). If not specified, the census parameter will default to 2018. 100200
sa2
String The Statistical Area 2 name for the requested census dataset (see census parameter). If not specified, the census parameter will default to 2018. 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. Kaimaumau
ur_id
String Urban rural ID. 1002
iur
String Urban rural indicator name. Rural settlement
iur_id
String Urban rural indicator ID. 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. 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. 060
con
String Constituency name. Te Hiku Constituency
con_id
String Constituency ID. 0101
maoricon
String Maori Constituency name. Okurei Maori Constituency
maoricon_id
String Maori Constituency ID. 0402
ward
String Ward name. Banks Peninsula Ward
ward_id
String Ward ID. 06016
cb
String Community Board name. Te Hiku Community
cb_id
String Community Board ID. 00101
tasub
String Territorial Authority Subdivision name. Akaroa Subdivision
tasub_id
String Territorial Authority Subdivision ID. 06019
landwater
String Land/Water description. Inlet
landwater_id
String Land/Water ID. 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

Location Params

Property Type Description
street String This filter restricts results to streets
suburb String This filter restricts results to suburbs.
city String This filter restricts results to cities.
region String This filter restricts results to regions.
region_code String Only return locations within the boundary of the selected region (Regional Authority).
strict String Determines how closely matched the results should be to the q parameter.
max Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.

Location metadata

Property Type Description Example
a
String Canonical location as supplied by Land Information New Zealand. Seaview Road, Glenfield, Auckland
pxid
String Unique location identifier. 1-.B.11.4.2H
street
String Holds the full name of the street. Note: The street attribute also includes the Street Type. Seaview Road
suburb
String The suburb or locality of the address as assigned by Land Information New Zealand. Glenfield
city
String The city, town or locality name as assigned by Land Information New Zealand. Auckland
region
String The Regional Authority in which this location exists. Note: Regional Authorities are the top tier of local government in New Zealand. Auckland Region
x
String Longitude coordinate (in WGS84 format). 174.643199
y
String Latitude coordinate (in WGS84 format). -36.426956
success
Boolean Indicates if the request was successful or not. true

Points of Interest Params

Property Type Description
max Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.

Points of Interest metadata

Property Type Description Example
name
String The name of the point of interest Whangarei Hospital
pxid
String Unique point of interest identifier. 3-.1.1d.2.42.1T.2
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
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
unit_identifier
String Identifies a specific sub dwelling. Can be alpha, number or a combination. 1
unit_type
String Describes the category of a sub-dwelling. flat
floor
String The level number and level type in a multi-story building. Level 19
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
building_name
String Holds the building or property name. Miban Building
suburb
String The suburb or locality of the address as assigned by Land Information New Zealand. Warkworth
post_suburb
String Name of the suburb when supplied by NZ Post. Manukau
city
String The city, town or locality name as assigned by Land Information New Zealand. Warkworth
mailtown
String Name of the town/city when supplied by NZ Post. Warkworth
ta
String The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. Auckland
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
rd_number
String The rural delivery number assigned by NZ Post to a rural address. 4
postcode
String Holds the four digit postcode. 0983
meshblock
String The meshblock identifier for the default census dataset. 146004
address_pxid
String Address identifier for the address of this point of interest. 2-.F.11.8.G.4
aims_address_id
Integer The unique identifier from Land Information New Zealand (LINZ). 103524
dpid
String A unique reference number assigned to each delivery address by NZ Post. 2668726
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
x
String Longitude coordinate (in WGS84 format). 174.643199
y
String Latitude coordinate (in WGS84 format). -36.426956
success
Boolean Indicates if the request was successful or not. true
  • Address Verification
    • Integration guide
    • Code examples
    • Widget code generator
    • Best practices
    • Fixing browser quirks
    • Advanced usage
    • Can't find your address?
    • Javascript widget reference (NZ)
    • Javascript widget reference (AU)
    • Javascript widget reference (Int'l)
    • Integration guide (Int'l)
  • Email Verification
    • Integration guide
    • Javascript reference
    • Code examples
    • Advanced usage
    • API reference
  • Phone Verification
    • Integration guide
    • Javascript reference
    • Code examples
    • Advanced usage
    • API reference
  • 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 (Service)
  • Privacy Statement (Website)
  • Terms & Conditions
  • Features
  • Address Autocomplete
  • Address Metadata
  • Address Verification
  • Bulk Address Cleansing
  • Address Geocoding
  • Email Address Verification
  • International Autocomplete
  • 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
  • Phone Verification
  • API Errors
  • AU APIs specs
  • International APIs
  • Widget Documentation
  • Address (NZ) Integration Guide
  • Address (NZ) Javascript Reference
  • Address (INT'L) Integration Guide
  • Address (INT'L) Javascript Reference
  • Email Integration Guide
  • Email Javascript Reference
  • Phone Integration Guide
  • Phone Javascript Reference
Addressfinder is also available in Australia
Terms and Conditions
Copyright © 2024 Addressfinder, New Zealand