API reference

This is a lightweight web service (REST interface), which provides an easy way to access and use every Addressfinder verification service.

If you find any bug, have any questions or suggestions please get in touch with us at support@addressfinder.com.

Not a developer?
Use Addressfinder's low- and no-code integrations.

Quick start

Make your first API call in minutes: sign up for a free account at portal.addressfinder.net to get your credentials and register your domains in the Portal (we include localhost by default).

To get a license key, sign up for a 30-day free trial.
Already have a subscription? Find your key in the Credentials section in the Portal.

Usage is billed per successful lookup, not API call. Learn more

Authentication

You can authenticate your API calls using two different methods:

Include your key and secret inside the HTTP GET request directly.
Add the secret in the Authorization headers of the request.

When using public-facing applications or client-side code, it's recommended to use header-based authentication to prevent exposing sensitive credentials in the URL (like your API secret), which could be logged or cached by browsers and intermediary services.

Example API call with the secret key in the headers

curl -H "Authorization: YOUR_API_SECRET" "https://api.addressfinder.io/api/nz/address/autocomplete/?key=YOUR_API_KEY&q=184%20will&format=json&strict=2"

You should only include the secret token for server-to-server API calls only.
For browser-based API calls, you will need to register the domain in the Portal.

Custom autocomplete service

We recommend that developers use Addressfinder's JavaScript widget to provide autocomplete capability to their users.

If you decide to write your own autocomplete service, then you will need to follow extra guidelines on top of using the Addressfinder API.

Make a GET request

Addressfinder is expecting that an HTTP GET request is made. Although an HTTP POST request is supported, it will add extra complexity. The user experience will be degraded with a POST request as a CORS pre-flight request will be required.

Use a simple request

Requests to the Addressfinder API from a browser are classified as Cross-Origin as they are made to a different domain than the main web page. These requests are subject to the CORS mechanisms which are built into all modern browsers.

Simple requests are HTTP GET requests that meet certain criteria such as allowing headers and content types.

Make a secure request (HTTPS)

You should always make requests to our secure endpoint using HTTPS. Support of unencrypted HTTP requests is only retained for backwards compatibility purposes, and will eventually be disabled.

In addition, use of HTTPS endpoint will allow the browser to make HTTP version 2 requests. These are substantially faster, and will give a better user experience.

Request origin

For authentication, the requests must be sent from a domain which has been registered in the Portal. The Referer header, which is automatically included by the browser, is used for this purpose.

Secret parameter

You should not include the API secret token in any of your API calls. The secret is intended for server-to-server API calls only. By including the secret in a browser-based API call, this value would be visible to third-parties. This could result in your account being abused by malicious parties.

The Addressfinder APIs perform a safety check to ensure that the secret value has not been included. It will return a 1008 error if the secret has been included.

Domain parameter

The domain parameter is not intended for use in the web browser. If you include it, the API will return an error result.

Address Autocomplete and Address Metadata APIs

The Address Autocomplete API must be used in conjunction with the Address Metadata API.

We expect that several calls to the Autocomplete API would be made as the user types in a portion of their address. The results of the Autocomplete API should be displayed to the user, normally in a popup style panel.

When the user identifies the desired address, they would select that address. At that point, you should make a call to the Address Metadata API. This would return all of the individual metadata for that address.

General Request Parameters

Include other request parameters in your request string as necessary. These will determine the types of addresses and data returned in the response.