Addressfinder frequently asked questions

General Addressfinder frequently asked questions below. We also have specific FAQs for each integration and you can use search to quickly find what you are after.

Technical - testing, compatibility and performance
Data - sources, definitions and database
Address services - verification and autocomplete
Email services - rules and definitions
Phone services - rules and definitions
Account and Plans - lookups, overage, plan changes

Technical

How should I test the service?

We recommend testing the service by searching a variety of addresses, emails or phone numbers and checking that the correct data populates your fields accurately.

Examples of test addresses to search with comments here

Is Addressfinder compatible with jQuery?

Yes. Addressfinder will work with JQuery or any other JavaScript framework. We have purposely built Addressfinder to be non-conflicting with all JavaScript libraries.

What browsers is the widget compatible with?

The Addressfinder widget is compatible with the majority of the latest browsers including: Chrome, Safari, Firefox, Edge and Internet Explore 6 to current.

The widget also works on the latest versions of Opera and Yandex but we do not actively support these browsers.

The Addressfinder Widget is compatible with most screen readers.

Does Addressfinder work with mobile phone applications?

Yes. One of the many features of Addressfinder is its low latency. We have worked hard to make the service as snappy as possible, including ensuring it is hosted in New Zealand to minimise network latency for Australian and New Zealand users. Low latency also helps when Addressfinder is used in mobile applications.

In addition, the Addressfinder Address Autocomplete Widget is very efficient and works well in a mobile context. We have implemented Addressfinder successfully on a number of mobile apps and websites. Generally the data returned by Addressfinder is quite small, so goes well over higher latency mobile networks.

Can Addressfinder handle my busy website?

Our current system architecture has been load tested to handle in excess of 10,000 requests per minute. Our system architecture scales horizontally, and we add additional server instances into our cluster as required.

Are you expecting to exceed several thousand requests per minute on launch? If so, we would appreciate advance notice as this will allow us to add additional server instances in advance of this event.

Can I write my own autocomplete service?

Yes. You will need to follow extra guidelines on top of using the Addressfinder API. Find these steps here.

The widget code generator was created to save you time and effort. We recommend developers use these to provide autocomplete to users.

What content security policy does Addressfinder require?

The Addressfinder widget requires permission from your content security policy (CSP) to:

Load our widget.js file
Make outgoing requests to the Addressfinder API
Load our stylesheet file

Our API and related assets are hosted on api.addressfinder.io.

We recommend the following values be added in your content security policy:

script-src https://api.addressfinder.io;
connect-src https://api.addressfinder.io;
style-src https://api.addressfinder.io;

Data

Where does the address information come from?

The Australia address data comes from three main sources: The Australia Post PAF (Postal Address File), G-NAF address database, the Australian Bureau of Statistics and augmented by Addressfinder database.

The New Zealand data comes from four main sources: The New Zealand Post PAF (Postal Address File), LINZ AIMS, Stats NZ, Open Street Maps and augmented by Addressfinder database.

The international address data comes from ESRI and HERE for addresses located in regions not covered by our regional datasets.

More details on these data sources and the associated AU, NZ and Int metadata available.

Are all possible Australian addresses listed in the Addressfinder database?

Pretty much. Addressfinder is Australia's most comprehensive address database with over 212 million official and alias addresses.

Updating monthly, we work with our data partners to ensure the database is as up to date as possible.

Read more about what addresses are in the dataset.

How often do you update your address databases?

Monthly. Both the Australian and New Zealand address databases are updated on a monthly basis.

Why do some addresses not appear in Addressfinder's database?

Here are some reasons why you might not be able to find an address with Addressfinder:

Custom filters - integration setting preventing certain addresses ie. PO Boxes.
New addresses - can take time to make it through authoritative data sources.
"Grey" addresses - addresses that have been used for a long time but not offical.

Read the detailed breakdown of these reasons

What happens when an address isn't in the database?

When a user enters an address that is not listed in the database, they will still be able to enter the address details manually. Addressfinder will still return addresses that are the closest matches to the address that has been entered, but if the correct address is not listed the user can complete the Address Line 1 entry, and then move on to 'Address Line 2, Suburb, Post Code etc'. Therefore you will not lose customers because their address is not available for selection from the drop down menu.

What is the difference between canonical and alias addresses?

Canonical addresses are the official addresses supplied to us by authoritative sources ie. Australia Post. The widget always selects this address by default.

Alias Addresses have unofficial address components including nearby suburbs or commonly misspelled street names. They are included in the database for ease of address selection. The default action of the widget is to take the alias and return the (corrected) canonical address.

The Addressfinder APIs will return both an id and a canonical_address_id.

Read the detailed breakdown of canoncial v alias addresses.

What's the difference between 'city' and 'mailtown' in New Zealand?

City is the physical town or city as named by LINZ. Mailtown is the town associated with the NZ Post delivery point.

If you would like to limit your search to addresses that are deliverable by NZ Post, you can collect only postal addresses.

Does every address record in Addressfinder have a DPID?

No, not every record in Addressfinder has a DPID. Only those addresses that have a "delivery point" are assigned an ID. These DPID fields come from the New Zealand Post PAF database. They identify those addresses that can have mail delivered by a postie.

As a result, some of your address records might not have a DPID against them. NZ Post typically do not deliver to addresses in the CBD of major cities, or to many rural destinations.

Within our system these addresses are sourced from Land Information New Zealand. The unique identifier for LINZ addresses is the aims_address_id field.

You can find out more about the various fields returned from Addressfinder in our API documentation

Address services

How can I disable the browser autofill?

Disabling the browser autofill is often a good idea as the autofilled addresses may contain errors and won't align with your config needs. Read our steps to do this.

How do I get NZ Post deliverable addresses?

It is possible to limit your search to postal addresses only, if your objective is to collect only addresses that NZ Post deliver to.

This is achieved by passing 'delivered:1' to the Address Autocomplete API or configuring in the widget constructor.

This parameter is accessible from the JavaScript widget using the address_params option.

What data is returned from the Address Verification API and Bulk service?

The data returned when verifying Australian Addresses is different to New Zealand address. In addition to the country, the dataset you are verifying addresses against also have an impact.

Why do some addresses change when selected by the user?

Some addresses change when they are selected because the selected address is an alias address and it is replaced with the correct canonical address.

Alias addresses contain unofficial or inaccurate address components. They are displayed in the search results, in order to better enable customers to find their address, once selected they are replaced with the correct, canonical address.

Email services

What are the default rules that are applied to the email verification widget?

In the absence of rules being specified in the widget code, the following rules will be applied by default:

Attribute	Default `rule`
`disposable`	block
`role`	allow
`public`	allow
`unverified`	block

What are the default messages that are displayed by the email verification widget?

In the absence of messages being specified in the widget code, the following default messages will be displayed if the response triggers one of the rules (default or supplied):

Response	Default `warn` message	Default `block` message
`disposable`	"This is a disposable email address."	"Disposable email addresses are not permitted."
`role`	"This is a group email address."	"Group email addresses are not permitted."
`public`	"This is a public email address."	"Public email addresses are not permitted."
`unverified`	"This email address could not be verified. Check spelling and retry."	"This email address could not be verified. Check spelling and retry."

What is a disposable email address?

Disposable email addresses are addresses that can be created with little effort, used for a fixed period of time, and then deleted. Examples of disposable email addresses include:

Hide My Email - from Apple and other premium providers
Throw-away email solutions - such as Mailinator or 10 Minute Mail ie.x9oxd2d@tmpnator.live

Addressfinders email service can be configured to block disposable email addresses which we generally recommend.

Alternatively configure to warn with custom message.

Find out more about email disposable email addresses

What is a catch all email domain?

A catch all domain, also known as ‘accept-all’ or ‘wild-card’, refers to a mail server that is configured to accept all emails sent to the domain regardless of the email account provided.

If the provided email account exists, emails sent to it will be delivered to that inbox. If the provided email account does not exist, emails sent to it will be delivered to a separate inbox that may or may not be monitored.

Phone services

What are the default rules applied by the Phone Verification widget?

In the absence of rules being specified in the widget code, the following default rules will be applied:

Attribute	Default `rule`
`unverified`	block
`countryNotAllowed`	block
`nonMobile`	allow

What are the default messages displayed by the Phone Verification widget?

In the absence of custom messaging being supplied in the widget code, the following default messages will be returned when the response matches the rules (supplied or default):

Response	Default `warn` message	Default `block` message
`unverified`	"Phone number not verified."	"Phone number not verified."
`countryNotAllowed`	"Preferred countries: {LIST}"	"Allowed countries: {LIST}"
`nonMobile`	"Mobile phone numbers preferred."	"Mobile phone numbers required."

What are all of the possible responses returned in the not_verified_code field of the Phone Verification API response?

LINE_DISCONNECTED
COUNTRY_NOT_ALLOWED
COUNTRY_NOT_SUPPORTED
LINE_TYPE_MUST_BE_MOBILE
INVALID_FORMAT

What are all possible responses returned in the line_status field of the Phone Verification API response?

connected
disconnected
indeterminate

What are all possible responses that may be returned in the line_type field of the Phone Verification API response?

Response	Description
fixed_line	A landline phone number. Not expected to be able to receive SMS messages.
mobile	A phone number associated with a mobile/cellular phone.
pager	A phone number associated with a pager device.
fixed_or_mobile	A phone number associated with either a fixed or mobile device.
toll_free	A toll-free phone number.
shared_cost	A shared cost phone number.
premium_rate	A premium rate phone number.
voip	A virtual phone number.
personal_number	A phone number designated for personal use.
uan	A universal access number, which can route incoming calls to different destinations.
voicemail	A phone number that is associated with a voicemail service.

Note: Not all of these line types are returned for every country.

Account and Plans

What is a lookup?

A ‘lookup’ is the term we use to measure the activity of your Addressfinder account.

One lookup is counted every time you or a user collects address metadata. This could happen when a user selects a verified address from the widget dropdown, or when you make a direct call to the Metadata API. The searching and display of addresses is not charged.

One lookup is also counted when an address verification call is made and Addressfinder considers the address to be valid. Invalid email addresses are not charged.

Lastly, one lookup is counted when using the address verification API, either via the portal or direct API. Only verified addresses are charged as a lookup.

What happens if I run out of lookups?

Monthly plan - If you use up 100% of your lookups while on a paid monthly plan, the Addressfinder service will continue. The extra lookups you use will be counted and you will be charged for these at the end of the month.

Annual plan - If you run out of lookups on an annual plan, your plan will automatically renew and start a new 12 month term.

You’ll know the roll-over’s coming because you will have received emails sent when you reached 80% and 95% of your plan’s limit. If you receive these emails very early in your plan's term you may wish to consider upgrading to a larger plan as this is likely to be more economical.

What are 'extra lookups' and how are they charged?

Monthly plans only - extra Lookups are the additional lookups or used on top of the prepaid lookups associated with your plan.

These extra lookups or overage charged at the same rate as your plan and is billed at the end of the month when your plan renews.

Annual plans do not have 'extra lookups'. When your plan runs out of lookups it will automatically renew early.

Change Type	When the change will take effect
Free trial to Paid	Immediately
Upgrade Monthly	Immediately
Upgrade Annual	At the end of the current term*
Downgrade Monthly	At the end of the current month
Downgrade Annual	At the end of the current term*