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 suggest testing the service by searching a variety of addresses and checking that the correct address data populates your address fields correctly.

Examples of test addresses to search:

Australian addresses to test	Notes
23 Hunter Street, BROOME WA 6725	Simple address - Check that the Street, Suburb, State and Postcode information is populated.
10/274 Harbour Drive, Coffs Harbour NSW 2450	Unit Address - check that the Unit and Street information is populated.
Unit 56, Level C, 12 Limburg Way, GREENWAY ACT 2900	Unit and Level Address - check that the unit, level and street information is populated.
Lot 453 Birds Road, CUSHNIE QLD 4608	Lot Address - Check that the lot information is populated.
PO Box 226, PORTLAND VIC 3305	PO Box address - check that the PO Box information is populated or that the PO Box addresses are not returned in the search results if you have filtered these out.

New Zealand addresses to test	Notes
32 Severn Street, Island Bay, Wellington 6023	Simple address - Check that the Street, Suburb, City and Postcode information is populated.
Flat 6, 14 Riverbank Street, Ebdentown, Upper Hutt 5018	Unit Address - check that the Unit and Street information is populated.
Suite 1, Level 4, 32 The Terrace, Wellington Central, Wellington 6011	Unit and Level Address - check that the unit, level and street information is populated.
95 Opiki Road, Opiki 4474	Rural Address - check that the city is populated and the suburb is empty.
952 Opiki Road, RD 4, Palmerston North 4474	Rural Mailing Address - Check that the RD number and city/mailtown information is populated.
PO Box 7734, Sydenham, Christchurch 8240	PO Box address - check that the PO Box information is populated or that the PO Box addresses are not returned in the search results if you have filtered these out.

How should I test the service?

We suggest testing the service by searching a variety of addresses and checking that the correct address data populates your address fields correctly.

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 widgets and code generator were created show you wouldn’t have to create your own. 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?

Addressfinder is Australia's most comprehensive address database with over 17 million official records. We achieve this by using the G-NAF database from PSMA, and the PAF database from Australia Post.

This means we have all the Australian addresses for:

Sending a letter or parcel with Australia Post
Using a courier firm to deliver a parcel
Finding a residential address for address verification purposes
Searching for the address of offices and other commercial premises
Identifying addresses in rural locations
Looking up a PO Box, Locked Bag, etc style address

Alias addresses

We supplement these official records with around 190 million alias addresses - these are sourced from the many combinations of historic street and suburb names, as well as vanity and neighbouring suburbs that can occasionally be used. These alias records all point to the official address so that you can always rely on the addresses you collect with Addressfinder.

With a combined address dataset of 212 million official and alias addresses, you'll find Addressfinder is the best choice for finding any address.

Are all possible New Zealand addresses listed in the Addressfinder database?

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?

Missing addresses

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

Custom filters
This is the most common reason for addresses not being returned in the autocomplete results. It occurs when the Addressfinder integration on a website has applied a filter to the search results. These prevent certain types of addresses from being returned in order to only collect addresses that comply with certain rules. Common filters include: excluding PO Boxes, only including addresses from a specific region or state, etc.

New addresses
The address data returned from the Addressfinder services comes from the providers listed above. These sources have their own update timetables so brand new addresses or subdivisions can take a little time to find their way into the database.
The Addressfinder dataset is refreshed monthly using the most recent dataset available from each provider.

"Grey" addresses
These are addresses that have been in use and accepted for a long time, but actually do not appear in any of the data sources used by Addressfinder. These addresses may include street corners, sections within larger industrial parks or care of type addresses. As long as these addresses remain unofficial they will not exist in the Addressfinder database.

How do I add an address to the database?
You should contact your local postal service (Australia Post, NZ Post, etc.) and request for an address to be added to their database. The request must come from a person residing at the address or the property owner. If the request is approved, the address will appear in our database the month after it has been processed by the postal service.

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

Canonical addresses are the official addresses that are supplied to us by the PSMA or Australia Post. They contain the correct street name, the correct suburb and are spelled correctly. By default, the Addressfinder widget always selects the canonical addresses when performing autocomplete and verification operations.

Alias Addresses

Alias addresses are addresses with unofficial address components. These may include nearby suburbs, commonly misspelled street names or older street names which have since been superseded. All of these potential alias addresses are included in the Addressfinder database in order to enable the user to find and select them. You will not receive this inaccurate address however as the default action of the widget is to return the (corrected) canonical address.

API Responses

The Addressfinder APIs will return both an id and a canonical_address_id. API developers can choose to mimic the Addressfinder widget behaviour by using the canonical_address_id field to query the Address Metadata API.

What's the difference between 'city' and 'mailtown' (NZ)?

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?

One of the features of Chrome and Safari is the user-controlled autofill settings. Autofill automatically identifies address fields and attempts to populate these with the user's address. This may seem like a good thing, but in reality, the autofilled address is just as likely to contain errors as any regular manually typed address. Also, the autofill address may not align with your needs (e.g. postal address).

Disable on Chrome

To disable the autofill on Chrome you need to change the autocomplete property to a non-standard value such as "disable-autocomplete".

<input
  type="text"
  name="property"
  autocomplete="disable-autocomplete"
/>

NB: The previous solution of setting autocomplete="off" no longer works. The solution above may also stop working at some stage.

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 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?

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 are created and displayed, in the search results, in order to better enable customers to find their address. As these alias addresses contain unofficial or inaccurate address components they need to be replaced with the correct address.

Alias addresses commonly occur with ranged addresses but also with nearby suburbs when a nearby suburb is used in the alias address. On selection the correct suburb is populated into the suburb field.

On rare occasions even more interesting alias addresses can exist where the number changes completely: For example, 253 Ross Road, YOOGALI NSW 2680 becomes 31 Ross Road, YOOGALI NSW 2680.

Or even better, the address appears to have nothing in common with the selected choice. For example, 32 Bryant Street, ASHGROVE QLD 4060 is actually 26 Jubilee Terrace, ASHGROVE QLD 4060. A little investigation tells us that the physical property is indeed at the corner of Bryant Street and Jubilee Terrace, which explains the odd behaviour.

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

This service is built into Apple and iCloud products. It is also included by several premium email providers.

It allows a person to hide their email address by generating a randomly-generated email address, and any emails received will be forwarded onto the person's private email address.

An example is:
mentolado.redisparo-5a@icloud.com

If you depend on sending emails in the longer term, it would be wise to warn or block disposable email addresses.

Throw-away email solutions

Services such as Mailinator or 10 Minute Mail offer short-term use of email addresses. They are not protected by passwords, and can have visibility to the general public.

An example is:
x9oxd2d@tmpnator.live

If you send emails containing sensitive or private information, you should block disposable email addresses.

Accepting disposable email addresses

There are very few reasons to accept disposable email addresses. There are many reasons to reject them, such as:

short term validity
fake or fraudulent signups
public visibility of sensitive or private data
increased email bounce rates
reduced dependability of email

Solution

The email verification widget can be configured to block all detected disposable email addresses.

Alternatively, you can configure the widget to warn the user without any blocking action. You can also provide a custom warning message if you desire.

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?

Default rules

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?

Extra Lookups are the additional lookups used on top of the prepaid lookups associated with your plan. These extra lookups are charged for at the end of the month when your plan renews.

For all of the Paid plans, the cost of extra lookups is pro-rata rated according to the size of your plan.

Can I change my plan whenever I like?

Yes. Change your plan when it suits you—for example, if your usage changes, or your organisation's financial needs change.

When will my plan change take effect?

The type of change you make will determine when the change takes place:

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*

*Annual plans will change early if you consume all your lookups.

Do you provide a developer account?

Yes. At our discretion we may provide you with a developer account. The developer account is specifically for development/digital agencies who add the Addressfinder service into multiple clients' systems.

The developer account has the following rules:

One developer account per agency.
For development purposes only.
Addressfinder staff are authorised to invite others from your agency to use the developer account.
When the integration is ready for production, the client is to create their own Addressfinder account and the credentials from this account used on an ongoing basis.

If you believe you qualify for a developer account, get in touch with us at support@addressfinder.com.au and we will create the account for you.

I'm a developer, how do I set up a client account?

If you are a developer who is integrating Addressfinder into one client's system, please make use of the Agile or Business Trial accounts for development. This account can then be passed over to the client once development is complete, or the client can use their own account.