Prefer OpenAPI 3.0 spec? Use Swagger UI or Redoc
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.
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, SE] | NZ |
Yes |
api_key |
Your API Key | YOUR_API_KEY |
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" }]
Successful response (SE):
[{ "street_number": "1", "street": "Storgatan", "locality": "Stockholm", "postcode": "11444", "district": "Stockholms Hedvig Eleonora", "municipality": "Stockholm", "lon": "18.080119", "lat": "59.335802", "formatted": "Storgatan 1, 114 44 STOCKHOLM" }]
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:
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"
See working examples of the autocomplete API in action on JSFiddle. Just bring your own API key.
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.849304 |
Yes |
lon |
The longitude of the location | 174.765469 |
Yes |
api_key |
Your API Key | YOUR_API_KEY |
Yes |
Successful response (NZ):
[{ "country_code": "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):
[{ "country_code": "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" }]
Successful response (SE):
[{ "country_code": "SE", "street_number": "1", "street": "Storgatan", "locality": "Stockholm", "postcode": "11444", "district": "Stockholms Hedvig Eleonora", "municipality": "Stockholm", "lon": "18.080119", "lat": "59.335802", "formatted": "Storgatan 1, 114 44 STOCKHOLM" }]
The reverse geocode response includes a country_code field (e.g. "NZ", "AU", "SE") 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:
https://api.addressable.dev/v2/reverse?api_key=YOUR_API_KEY&lat=-36.849304&lon=174.765469
Sample cURL code:
curl "https://api.addressable.dev/v2/reverse?api_key=YOUR_API_KEY&lat=-36.849304&lon=174.765469"
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 | YOUR_API_KEY |
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"
| HTTP Code | Response |
|---|---|
| 400 |
{"errors":[{"error_type":"request","message":"Query parameter q is required"}]}
|
| 401 |
{"errors":[{"error_type":"request","message":"API key invalid"}]}
|
| 406 |
{"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"}]}
|
| 429 |
{"errors":[{"error_type":"request","message":"Rate limit exceeded"}]}
|
Requests are rate limited per calendar day (UTC timezone).
| Account Type | Daily Limit |
|---|---|
| Free | 100 requests |
| Subscribed | 30,000 requests |
When the limit is exceeded, requests return a 429 response. See Pricing for details.