Documentation - Getting Started

Create the code snippet

licence key

Get a licence key or, if you have one, login to the portal to get it.

ID of address input

Right click on your address field and click 'Inspect element'. The ID will look like: <input id="address_field">

Country

New Zealand
Australia
Both countries
ID of country selector

This field determines which addresses are displayed. When either AU or NZ is selected we will only display addresses from that country.

Address collection

I capture addresses in a single line
I capture my address elements separately (street, suburb, postcode, etc)

Get the code

Copy and paste this code into the HTML of your website, directly above the closing </body> tag. Copy the code to your clipboard

Read the Integration Instructions

Frequently asked questions

What metadata fields can I collect with each address?

The metadata fields available for collection vary according to the address that is being collected but can include:

Field Name	Description
a	Canonical address as supplied by Land Information New Zealand or NZ Post.
postal	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.
building_name	Holds the building or property name.
unit_type	Describes the category of a sub-dwelling.
unit_identifier	Identifies a specific sub dwelling. Can be alpha, number or a combination.
floor	The level number and level type in a multi-story building.
number	The street number of the address. Also populated with the box number for PO Box type addresses.
alpha	Holds the alpha component of a street number. In the address 1B High Street, B is the alpha.
street	Holds the full name of the street. Note: The street attribute also includes the Street Type.
street_name	Holds the name of the street.
street_type	The type of street.
suburb	The suburb or locality of the address as assigned by Land Information New Zealand.
city	The city, town or locality name as assigned by Land Information New Zealand.
box_type	The type of PO Box/CMB/Private Bag/Counter Delivery.
lobby_name	The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located.
rd_number	The rural delivery number assigned by NZ Post to a rural address.
post_suburb	Name of the suburb when supplied by NZ Post.
mailtown	Name of the town/city when supplied by NZ Post.
postcode	Holds the four digit postcode.
dpid	A unique reference number assigned to each delivery address by NZ Post.
primary_parcel_id	The unique identifier of the portion of land associated with the selected address.
aims_address_id	The unique identifier from Land Information New Zealand (LINZ).
x	Longitude coordinate (in WGS84 format).
y	Latitude coordinate (in WGS84 format).
meshblock	The meshblock identifier for the requested census dataset (see `census` parameter). If not specified, the Census parameter will default to 2018.
sa1_id	Statistical area 1 (2018 census only)
sa2_id	Statistical area 2 ID (2018 census only)
sa2	Statistical area 2 name (2018 census only)
rural	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.
ur	Urban rural name (2018 census only)
ur_id	Urban rural ID (2018 census only)
iur	Urban rural indicator name (2018 census only)
iur_id	Urban rural indicator ID (2018 census only)
aims_road_section_id	The unique road section identifier from Land Information New Zealand (LINZ).
region	The Regional Authority in which this address exists. Note: Regional Authorities are the top tier of local government in New Zealand.
region_id	Region ID (2018 census only)
ta	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand.
ta_id	Territorial Authority ID (2018 census only)
con	Constituency name (2018 census only)
con_id	Constituency ID (2018 census only)
maoricon	Maori Constituency name (2018 census only)
maoricon_id	Maori Constituency ID (2018 census only)
ward	Ward name (2018 census only)
ward_id	Ward ID (2018 census only)
cb	Community Board name (2018 census only)
cb_id	Community Board ID (2018 census only)
tasub	Territorial Authority Subdivision name (2018 census only)
tasub_id	Territorial Authority Subdivision ID (2018 census only)
landwater	Land/Water description (2018 census only)
landwater_id	Land/Water ID (2018 census only)
address_line_1	First line of the non-suburb/city/postcode portion of the address
address_line_2	Second line of the non-suburb/city/postcode portion of the address.
pxid	Unique address identifier.
success	Indicates if the request was successful or not.

Field Name	Description
full_address	Full address string. FAQ: alias address vs canonical address.
id	The unique address identifier. This ID will change following a data refresh.
canonical_address	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.
canonical_address_id	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.
latitude	Latitude coordinate (in WGS84 format).
longitude	Longitude coordinate (in WGS84 format).
lot_identifier	Identifies a specific lot on a site. Can be an alpha, number or a combination.
box_identifier	The number portion of a PO Box address
box_type	The type portion of a PO Box address, including `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD`
site_name	Holds the address element that identifies the name of a site or building.
level_type	Describes the level type within a multi-level building.
level_number	Identifies a specific level within a multi-level building. Can be an alpha, number or a combination.
unit_type	Describes the category of a sub-dwelling.
unit_identifier	Identifies a specific sub-dwelling. Can be an alpha, number or a combination.
street_number_1	The number of the building on the street.
street_number_2	Holds the upper bound when this is a ranged address. For single number addresses this field is `null`
street	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.
street_name	Holds the name of the street. Note: This attribute does not include the street type or suffix.
street_type	The type of street.
street_suffix	The suffix of the street. Typically contains a compass direction.
locality_name	The locality/suburb of this address.
state_territory	The Australian state or territory where the address is located.
postcode	Holds the four digit postcode.
address_line_1	First line of the non-locality/state/postcode portion of the address
address_line_2	Second line of the non-locality/state/postcode portion of the address. This will be `null` for addresses without a unit/level/etc number.
success	Indicates if the request was successful or not.
dpid	Australia Post delivery point identifier.
lga_name	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
lga_type_code	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`.
legal_parcel_id	Government legal property description.
meshblock	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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.
sa1_id	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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.
sa2_id	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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.
gnaf_id	The unique persistent identifier of the G-NAF address.

Metadata Fields for Australia

Metadata fields for New Zealand

How do I collect the full address when I don’t have an ‘address_line_2’ field on my form?

The AddressFinder widget is configured to populate the addresses elements into five fields (address line 1, address line 2, suburb, city, postcode) but not everyone has these fields on their form.

If your form does not have an address line 2 then the widget can be adjusted to populate the data from address lines 1 and 2 into one field.

Insert line 12 of this Code Example into your widget Javascript.

The AddressFinder widget is configured to populate the addresses elements into five fields (address line 1, address line 2, suburb, state, postcode) but not everyone has these fields on their form.

If your form does not have an address line 2 then the widget can be adjusted to populate the data from address lines 1 and 2 into one field.

Insert lines 15 - 21 of this Code Example into your widget Javascript.

The AddressFinder widget is configured to populate the addresses elements into five fields (address line 1, address line 2, suburb, state/city, postcode) but not everyone has these fields on their form.

If your form does not have an address line 2 then the widget can be adjusted to populate the data from address lines 1 and 2 into one field.

For New Zealand insert line 12 of this Code Example into your widget Javascript.

For Australia insert lines 15 - 21 of this Code Example into your widget Javascript.

Can the region/state filters be used to include more than one region/state?

No. The New Zealand widget "region_code" parameter can only be used to restrict address searches to one region

Yes - you can enable the searching of more than one state/territory by adding the all of the desired State/Territory codes to your widget javascript. Make use of the code example below to add these codes.

{ address_params: {"state_codes": "QLD,NSW”} }

Code	State / Territory
ACT	Australian Capital Territory
NSW	New South Wales
NT	Northern Territory
OT	Other Territories
QLD	Queensland
SA	South Australia
TAS	Tasmania
VIC	Victoria
WA	Western Australia

Unfourtunately this is not possible with the New Zealand widget. The region_code parameter only works with one region code. { address_params: {"region_code": "1”} }

This is possible with the Australian widget. You can add your desired State/Territory codes into the state codes address parameter: { address_params: {"state_codes": "QLD,NSW”} }

Code	State / Territory
ACT	Australian Capital Territory
NSW	New South Wales
NT	Northern Territory
OT	Other Territories
QLD	Queensland
SA	South Australia
TAS	Tasmania
VIC	Victoria
WA	Western Australia

Can I search and collect different types of addresses from different places on my website?

Yes - It is common to need to collect both a residential address and a postal address on the same form. To do this you will need to include the Javascript widget to your page twice and have each one configured for the specific address needs. See a code example here.

AddressFinder

Interactive Widget Code Generator

On the form below, select the options applicable to your addressing needs. Then copy the updated javascript, at the bottom, for use on your website / form

Create the code snippet

Options for collecting additional metadata

Display options

Get the code