Documentation

Prefer OpenAPI 3.0 spec? Use Swagger UI or Redoc

Building with Coding Agents

If you use an AI coding agent (Cursor, Claude Code, GitHub Copilot, etc.), you can bootstrap an integration very quickly. We suggest a prompt like this:

On the {screen_name} screen, the {field_name} field should be a typeahead address lookup.
It should proxy through an endpoint on our server (to keep the API key server-side) and call the Addressable API documented at https://www.addressable.dev/openapi.yml.
ADDRESSABLE_API_KEY is already set in {environment_variable_location}.
Use country_code={XX} for all requests.
Only call the API after the user has typed at least 3 characters, and debounce input by 300ms, to protect against rate limits.
When a user selects an address result, populate the form fields {field_1}, {field_2}, {field_3} with the matching values from the result.

Authentication

All requests must be authenticated with a valid API key as a GET parameter. API keys are available in your account after free registration

A missing or invalid API key will result in a 401 response.

CORS: Cross-Origin Resource Sharing is enabled on the API endpoints so you can use the service from your javascript application.

Autocomplete

Description: Lookup possible addresses that match the partial address query value. 4-6 numbers and characters is typically enough to identify an address.

Endpoint: https://api.addressable.dev/v2/autocomplete

HTTP Method: GET

Successful response (NZ):

Successful response (AU):

Successful response (SE):

Output fields for each result:

AU: building_name unit_details street_number street locality region postcode meshblock lon lat formatted

NZ: street_number street locality city region postcode meshblock lon lat formatted

SE: street_number street locality postcode district municipality lon lat formatted

All fields except formatted may be null depending on the granularity of the match (e.g. street-level results will have a null street_number).

When no addresses match the query, the API returns HTTP 200 with an empty array [].

Sample GET query:

Sample cURL code:

Examples

See working examples of the autocomplete API in action on JSFiddle. Just bring your own API key.

CoreJS Typeahead + Bootstrap

Awesomplete

Reverse Geocode

Description: Convert geographic coordinates into a human-readable address or place name.

Endpoint: https://api.addressable.dev/v2/reverse

HTTP Method: GET

Successful response (NZ):

Successful response (AU):

Successful response (SE):

The reverse geocode response includes a country_code field (e.g. "NZ", "AU", "SE", "EE", "CA") indicating which country the coordinates resolved to.

Output fields for each result:

AU: country_code building_name unit_details street_number street locality region postcode meshblock lon lat formatted

NZ: country_code street_number street locality city region postcode meshblock lon lat formatted

SE: country_code street_number street locality postcode district municipality lon lat formatted

All fields except formatted may be null depending on the granularity of the match (e.g. street-level results will have a null street_number).

Sample GET query:

Sample cURL code:

Profile

Description: Check identity or subscription expiry

Endpoint: https://api.addressable.dev/v2/profile

HTTP Method: GET

Successful response:

Sample GET query:

Sample cURL code:

Possible Error Responses:

{"errors":[{"error_type":"request","message":"Query parameter q is required"}]}

{"errors":[{"error_type":"request","message":"API key invalid"}]}

{"errors":[{"error_type":"request","message":"Unrecognised country code"}]}

{"errors":[{"error_type":"request","message":"Invalid type value"}]}

{"errors":[{"error_type":"request","message":"Invalid max_results value"}]}

{"errors":[{"error_type":"request","message":"Coordinates not within expected country bounds"}]}

{"errors":[{"error_type":"request","message":"Lon can't be blank"}]}

{"errors":[{"error_type":"request","message":"Lat can't be blank"}]}

{"errors":[{"error_type":"request","message":"Lat must be between -90 and 90"}]}

{"errors":[{"error_type":"request","message":"Lon must be between -180 and 180"}]}

{"errors":[{"error_type":"request","message":"Rate limit exceeded"}]}

Rate Limits

Requests are rate limited per calendar day (UTC timezone).

When the limit is exceeded, requests return a 429 response. See Pricing for details.