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
    • 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
      • API Errors
      See all API docs
  • Log in
  • Get Started Free

Widget documentation

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. Add any of the Address params. The Code Demos page has some good examples.
address_metadata_params Object nil Additional parameters to adjust the values returned from the Address Metadata API. Add any of the Address Metadata API parameters.
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.

New Zealand 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.

New Zealand 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 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

New Zealand 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.

New Zealand 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-.3.19.1.h
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

New Zealand 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.

New Zealand 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 requested census dataset (see census parameter). If not specified, the Census parameter will default to 2018. 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

Australian Address Params

Property Type Description
gnaf String Returns physical addresses from the GNAF dataset (supplied by the Australian Government).
au_paf String Returns postal addresses from the PAF dataset. These are addresses which Australia Post deliver mail to and StarTrack and eParcel deliver parcels to.
post_box String Return PO Box style addresses. This includes PO Box, Locked Bag, GPO Box, CMB, RMS, Care PO, MS and RSD. Used with the au_paf=1 filter above.
canonical String Return canonical and/or alias addresses - this allows for vanity suburbs, historic street names, and more.

FAQ: What is the difference between canonical and alias addresses
state_codes String Filter the results according to the states or territories. Use a comma to separate multiple values
max Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.

Australian Address metadata

Key

GNAF Returned (if present) when searching the gnaf database.

PAF Returned (if present) when searching the au_paf database.

Property Type Description Example
full_address
GNAF PAF
String Full address string. FAQ: alias address vs canonical address. 13 Neville Street, RYDE NSW 2112
id
GNAF PAF
String The unique address identifier. This ID will change following a data refresh. 8097e3df-a3ab-43ad-bc66-22c8f5812361
canonical_address
GNAF PAF
String The canonical or official full address string associated with this address. Can differ from the full_address in either street number, locality name or state name. FAQ: alias address vs canonical address. 11-15 Neville Street, RYDE NSW 2112
canonical_address_id
GNAF PAF
String The ID of the canonical or official address associated with this search result.

Note: The ID and Canonical Address ID will be identical when the search result is canonical. FAQ: alias address vs canonical address.		 d70230a9-a3d8-402f-971e-1b798d00f2f5
latitude
GNAF PAF
String Latitude coordinate (in WGS84 format). -37.899031
longitude
GNAF PAF
String Longitude coordinate (in WGS84 format). 144.999530
lot_identifier
GNAF PAF
String Identifies a specific lot on a site. Can be an alpha, number or a combination. 3
box_identifier
PAF
String The number portion of a PO Box address 123
box_type
PAF
String The type portion of a PO Box address, including PO Box, Locked Bag, GPO Box, CMB, RMS, Care PO, MS and RSD PO Box
site_name
GNAF PAF
String Holds the address element that identifies the name of a site or building. Kenilworth Police Station
level_type
GNAF PAF
String Describes the level type within a multi-level building. Basement
level_number
GNAF PAF
String Identifies a specific level within a multi-level building. Can be an alpha, number or a combination. 3
unit_type
GNAF PAF
String Describes the category of a sub-dwelling. Suite
unit_identifier
GNAF PAF
String Identifies a specific sub-dwelling. Can be an alpha, number or a combination. 2
street_number_1
GNAF PAF
String The number of the building on the street. 1703
street_number_2
GNAF PAF
String Holds the upper bound when this is a ranged address. For single number addresses this field is null 1705
street
GNAF PAF
String Holds the full name of the street. This attribute is a composite of the street name, the street type, and the street suffix if present. Queen Street North
street_name
GNAF PAF
String Holds the name of the street. Note: This attribute does not include the street type or suffix. Queen
street_type
GNAF PAF
String The type of street. Street
street_suffix
GNAF PAF
String The suffix of the street. Typically contains a compass direction. North
locality_name
GNAF PAF
String The locality/suburb of this address. KATOOMBA
state_territory
GNAF PAF
String The Australian state or territory where the address is located. NSW
postcode
GNAF PAF
String Holds the four digit postcode. 0983
address_line_1
GNAF PAF
String First line of the non-locality/state/postcode portion of the address Unit 209
address_line_2
GNAF PAF
String Second line of the non-locality/state/postcode portion of the address. This will be null for addresses without a unit/level/etc number. 274 Harbour Drive
success
GNAF PAF
Boolean Indicates if the request was successful or not. true
dpid
PAF
String Australia Post delivery point identifier. 99119187
lga_name
GNAF
String The name of the Local Government Area in which the address is located. These values are provided by the ABS and are an approximation of the gazetted local government boundaries.
Code example - collect LGA data		 Bundaberg
lga_type_code
GNAF
String The code relating to the type (or status) of the Local Government Area. Codes used are Area A, Aboriginal Council AC, Borough B, City C, District Council DC, Municipality / Municipal Council M, Regional Council R or RegC, Rural City RC, Shire S and Town T. DC
legal_parcel_id
GNAF
String Government legal property description. 10//SP9489
meshblock
GNAF
String The meshblock identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census.

The format is MB, followed by a 2 digit year identifier, followed by the 11 digit meshblock identifier.		 MB1610671120000
sa1_id
GNAF
String The statistical area (SA1) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. 12602159143
sa2_id
GNAF
String The statistical area (SA2) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. 126021591
gnaf_id
GNAF
String The unique persistent identifier of the G-NAF address. GANSW705051429

Australian Location Params

Property Type Description
location_types String Show only locations of the supplied type. Use a comma to separate multiple values.
state_codes String Filter the results according to the states or territories. Use a comma to separate multiple values.
max Integer The maximum number of results to return. A number between 1 and 100. The default is 10 results.

Australian Location metadata

Property Type Description Example
full_location
String Full location string. Mathers Road East, WALKERVILLE VIC 3959
location_type
String The kind of location. Valid values include street, locality or state. street
latitude
String Latitude coordinate (in WGS84 format). -38.77287906
longitude
String Longitude coordinate (in WGS84 format). 146.10907797
street_name
String Holds the name of the street. Note: This attribute response does not contain the street type. Mathers
street_type
String The type of street. Road
street_suffix
String The suffix of the street. Typically contains a compass direction. East
street
String The full street name. Note: This attribute response contains the street name, street type and street suffix. Mathers Road East
locality_name
String The locality/suburb of this address. WALKERVILLE
state_territory
String The Australian state or territory containing the location VIC
postcode
String The postcode assigned to a locality (for 'locality' locations), or to the locality a street is in (for 'street' locations). 3959
success
Boolean Indicates if the request was successful or not. true

International Address Params

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

International Address metadata

Property Type Description Example
id
String Unique address identifier obtained from the Address Autocomplete 2fjZ2wvSHufT0ruefqNH13rYtBKS6ZZukGxPowcuqmUB/s_nIJl_--trguceJRa_eztyLG--jl1iVIoZZZaQYvF/erphow==
address
Group Address information as supplied by our sources. Contains the following fields:
address_line_1
String
 First address line in the country specific format, usually includes unit number, street number, name, etc. Can be used on forms with multiple address fields. 123 Edward St
address_line_2
String
 Second address line in the country specific format, usually includes locality, neighbourhood, etc. Can be used on forms with multiple address fields. Silver Berry
address_line_combined
String
 Country specific lines 1 and 2 combined into one. Can be used on forms with a single address field. 123 Edward St, Silver Berry
city
String
 The city, town or locality name as assigned by our sources Toronto
city_line
String
 The city in a format suitable for postal services Toronto ON M5G
postcode
String
 Holds the country specific postcode M5G
state
String
 Country specific state/region/district ON
country_name
String
 Name of the country the address belongs to Canada
country_code
String
 ISO 3166-1 alpha-2 code of the country CA
metadata
Group Other metadata as supplied by our sources. Contains the following fields:
street
String
 Holds the full name of the street as supplied by our sources Edward St
street_number
String
 Holds the street number as supplied by our sources 123
state_code
String
 Holds the two letter code of the province ON
state_name
String
 Holds the full name of the province Ontario
position
Group Contains the GPS coordinates if requested via the gps param
latitude
Float
 Latitude in the decimal degrees format 42.993184
longitude
Float
 Longitude in the decimal degrees format -81.184534
success
Boolean Indicates if the request was successful or not. true
  • Widget class
  • Service class
  • NZ Address params
  • NZ Address metadata
  • NZ Location params
  • NZ Location metadata
  • NZ Points of Interest
    params
  • NZ Points of Interest
    metadata
  • AU Address params
  • AU Address metadata
  • AU Location params
  • AU Location metadata
  • International Address
    params
  • International Address
    metadata

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 Address Lookup
  • Points of Interest
  • Street, Suburb & City Search
  • Bounding Box Search
  • Postcode Finder

Integrations

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

API Documentation

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

Widget Documentation

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

AddressFinder is also available in Australia

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.