Documentation

Prefer OpenAPI 3.0 spec? Use Swagger UI or Redoc

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

Parameter	Description	Example	Required
`q`	The address query string. Can be a partial address	`220 Queen St Auc`	Yes
`country_code`	The ISO 3166 Country Code. Accepted: [AU, NZ]	`NZ`	Yes
`api_key`	Your API Key	`O3xtxU8vlJ8M9hsTVD-6_g`	Yes
`type`	A comma separated list of field types. Accepted: [number, street, locality]. Filters results to include only the types specified. Example usage: use the "street" filter to only include one result for each street, and exclude street-number-granularity results. Example usage: use the "locality" filter when running autocomplete for a suburb form field to exclude street or number results. Default will search all field types.	`street,locality`	No
`max_results`	Maximum number of results to return. Must be an integer from 1 to 10. Default: 5.	`10`	No

Successful response (NZ):

[{ "street_number": "214-220", "street": "Queen Street", "locality": "Auckland Central", "city": "Auckland", "region": "Auckland", "postcode": "1010", "meshblock": "0437101", "lon": 174.765469, "lat": -36.849304, "formatted": "214-220 Queen Street, Auckland Central, Auckland" }]

Successful response (AU):

[{ "building_name": null, "unit_details": null, "street_number": "26-28", "street": "Ramsay Street", "locality": "Rochester", "region": "VIC", "postcode": "3561", "meshblock": "20098880000", "lon": "144.699065", "lat": "-36.359784", "formatted": "26-28 Ramsay Street, Rochester, VIC 3561" }]

Output fields for each result:

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

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

Sample GET query:

https://api.addressable.dev/v2/autocomplete?api_key=YOUR_API_KEY&country_code=NZ&q=220+Queen+Auc

Sample cURL code:

curl "https://api.addressable.dev/v2/autocomplete?api_key=YOUR_API_KEY&country_code=NZ&q=220+Queen+Auc"

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

Parameter	Description	Example	Required
`lat`	The latitude of the location	`-36.850712`	Yes
`lon`	The longitude of the location	`174.764605`	Yes
`api_key`	Your API Key	`O3xtxU8vlJ8M9hsTVD-6_g`	Yes

Successful response (NZ):

[{ "street_number": "214-220", "street": "Queen Street", "locality": "Auckland Central", "city": "Auckland", "region": "Auckland", "postcode": "1010", "meshblock": "0437101", "lon": 174.765469, "lat": -36.849304, "formatted": "214-220 Queen Street, Auckland Central, Auckland" }]

Successful response (AU):

[{ "building_name": null, "unit_details": null, "street_number": "26-28", "street": "Ramsay Street", "locality": "Rochester", "region": "VIC", "postcode": "3561", "meshblock": "20098880000", "lon": "144.699065", "lat": "-36.359784", "formatted": "26-28 Ramsay Street, Rochester, VIC 3561" }]

Output fields for each result:

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

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

Sample GET query:

https://api.addressable.dev/v2/reverse?api_key=YOUR_API_KEY&lat=-36.850712&lon=174.764605

Sample cURL code:

curl "https://api.addressable.dev/v2/reverse?api_key=YOUR_API_KEY&lat=-36.850712&lon=174.764605"

Profile

Description: Check identity or subscription expiry

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

HTTP Method: GET

Parameter	Description	Example	Required
`api_key`	Your API Key	`O3xtxU8vlJ8M9hsTVD-6_g`	Yes

Successful response:

{"email":"[email protected]","subscription_expires_on":"2025-01-01"}

Sample GET query:

https://api.addressable.dev/v2/profile?api_key=YOUR_API_KEY

Sample cURL code:

curl "https://api.addressable.dev/v2/profile?api_key=YOUR_API_KEY"

Possible Error Responses:

HTTP Code	Response
401	{"errors":[{"error_type":"request","message":"API key invalid"}]}
429	{"errors":[{"error_type":"request","message":"Rate limit exceeded"}]}