API Specification

Guide to Address API authentication, response codes and more

API Access Key

An API Key is required to access the following address APIs:

Sign up for a free account to get started.

API Authentication

The API key can be passed to an API end-point via the request header or as a query string parameter. The supported query string or request header parameters are:

  • key
  • addy-api-key
  • x-addy-api-key
  • api_key

An example of a query string parameter is shown below to search for "80 Queen":

  • https://api.addy.co.nz/search?key=YOUR-API-KEY&s=80+Queen

Please read the API Key Best Practices for more information.

Content Types

The supported request and response content types are documented below.
Use the API Tester to toggle and discover the response types using the "Response Content Type" drop-down.

Request Formats application/json
Response Formats application/json

Response Codes

The following HTTP status codes are returned by the API:

Code Type Description
200 OK The request was successful. A valid JSON, JSONP or XML response will be returned.
400 Bad Request The request is invalid (e.g. invalid parameters).
401 Unauthorized The API Key is invalid or missing.
500 Internal Server Error An unexpected condition was encountered.


Tagging provides the ability to identify requests to simplify billing and grouping. Tagging is useful for Software-as-a-Service applications, where a single site-wide API key is used for calling Addy's address API. Tagging enables your business to filter usage reports based on tenant tags or unique identifiers.

Parameter Name Description Example
tag Provide a tag for the request /search?tag=sales
uniqueid Provide a unique ID for the request /search?uniqueid=12345