# Addressable API Documentation

Machine-readable contract: [OpenAPI 3.0 spec](https://www.addressable.dev/openapi.yml). HTML version of this page: https://www.addressable.dev/pages/documentation

## Integration guidance

- Proxy requests through your own server so the API key stays server-side.
- Only call autocomplete after the user has typed at least 3 characters, and debounce input by 300ms, to stay within rate limits.
- When the user selects a result, populate your form fields from the matching result fields.

## Authentication

All requests must be authenticated with a valid API key as a GET parameter (`api_key`). API keys are available in your account after free registration: https://www.addressable.dev/users/sign_up

A missing or invalid API key results in a 401 response.

CORS: Cross-Origin Resource Sharing is enabled on the API endpoints, so the service can be called from browser JavaScript.

## Autocomplete

Look up addresses that match a partial address query. 4-6 numbers and characters is typically enough to identify an address.

`GET https://api.addressable.dev/v2/autocomplete`

| Parameter | Required | Description | Example |
| --- | --- | --- | --- |
| `q` | Yes | The address query string. Can be a partial address. | `220 Queen St Auc` |
| `country_code` | Yes | ISO 3166 country code. Accepted: AU, BE, CA, DK, EE, FI, FO, GL, IS, LT, LV, NO, NZ, SE, US | `NZ` |
| `api_key` | Yes | Your API key | `YOUR_API_KEY` |
| `type` | No | Comma-separated field types: `number`, `street`, `locality`. Filters results to only those types. Use `street` for one result per street (no street-number results); use `locality` for a suburb field. Default: all types. | `street,locality` |
| `max_results` | No | Maximum results to return, an integer from 1 to 10. Default: 5. | `10` |

Successful response (NZ):

```json
[{"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):

```json
[{"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):

```json
[{"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"}]
```

Successful response (EE):

```json
[{"street_number":"19-89","street":"J. Koorti tn","locality":"Lasnamäe linnaosa","postcode":"13623","district":"Harju maakond","municipality":"Tallinn","lon":"24.831852","lat":"59.441451","formatted":"J. Koorti tn 19-89, 13623 Lasnamäe linnaosa"}]
```

Successful response (FI):

```json
[{"street_number":"1","street":"Mannerheimintie","locality":"Helsinki","postcode":"00100","municipality":"Helsinki","lon":"24.940524","lat":"60.171260","formatted":"Mannerheimintie 1, 00100 Helsinki"}]
```

Successful response (DK):

```json
[{"street_number":"1","street":"Rådhuspladsen","locality":"København V","postcode":"1550","region":"Region Hovedstaden","municipality":"København","lon":"12.566679","lat":"55.675941","formatted":"Rådhuspladsen 1, 1550 København V"}]
```

Successful response (IS):

```json
[{"street_number":"1","street":"Laugavegur","locality":"Reykjavík","postcode":"101","region":null,"municipality":"Reykjavík","lon":"-21.937800","lat":"64.146600","formatted":"Laugavegur 1, 101 Reykjavík"}]
```

Successful response (NO):

```json
[{"street_number":"22","street":"Karl Johans Gate","locality":"Oslo","postcode":"0026","region":null,"municipality":"Oslo","lon":"10.749100","lat":"59.913700","formatted":"Karl Johans Gate 22, 0026 Oslo"}]
```

Successful response (FO):

```json
[{"street_number":"1","street":"Bryggjubakki","locality":"Tórshavn","postcode":"100","region":null,"municipality":"Tórshavnar kommuna","lon":"-6.769000","lat":"62.012100","formatted":"Bryggjubakki 1, 100 Tórshavn"}]
```

Successful response (GL):

```json
[{"street_number":"1","street":"Aqqusinersuaq","locality":"Nuuk","postcode":"3900","region":null,"municipality":"Kommuneqarfik Sermersooq","lon":"-51.721400","lat":"64.183300","formatted":"Aqqusinersuaq 1, 3900 Nuuk"}]
```

Successful response (CA):

```json
[{"unit":null,"street_number":"350","street":"Sparks Street","locality":"Ottawa","region":"ON","postcode":"K1R 7S8","lon":"-75.70032","lat":"45.42111","formatted":"350 Sparks Street, Ottawa, ON K1R 7S8"}]
```

Output fields for each result, by country:

- AU: `building_name`, `unit_details`, `street_number`, `street`, `locality`, `region`, `postcode`, `meshblock`, `lon`, `lat`, `formatted`
- BE: `street_number`, `unit_details`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- CA: `street_number`, `street`, `locality`, `city`, `region`, `postcode`, `lon`, `lat`, `formatted`
- DK: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- EE: `street_number`, `street`, `locality`, `postcode`, `district`, `municipality`, `lon`, `lat`, `formatted`
- FI: `street_number`, `street`, `locality`, `postcode`, `municipality`, `lon`, `lat`, `formatted`
- FO: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- GL: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- IS: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- LT: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- LV: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `lon`, `lat`, `formatted`
- NO: `street_number`, `street`, `locality`, `postcode`, `region`, `municipality`, `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`
- US: `street_number`, `street`, `locality`, `city`, `region`, `postcode`, `lon`, `lat`, `formatted`

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

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

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

## Geocode

Resolve one complete, free-text address to its single best match. Use this when an address arrives whole (pasted from a website or email signature, imported from a spreadsheet, or already stored) rather than typed into an autocomplete field.

`GET https://api.addressable.dev/v2/geocode`

| Parameter | Required | Description | Example |
| --- | --- | --- | --- |
| `q` | Yes | The full address (max 256 characters) | `Level 2, 24 Marine Parade, Bluff Hill, Napier 4110` |
| `country_code` | Yes | ISO 3166 country code. Available for AU, BE, CA, DK, EE, FI, FO, GL, IS, LT, LV, NO, NZ, SE, US | `NZ` |
| `api_key` | Yes | Your API key | `YOUR_API_KEY` |

Levels, floors, building names, rural delivery numbers, PO boxes, the postcode, the state and the country name are tolerated, as are misspelt street names, number ranges ("87-93") and corners ("Corner of A & B"). When the street number or the street cannot be found the result falls back to the street or the suburb.

The response is an array with at most one result: the autocomplete fields for that country plus

- `match_level`: `number`, `street` or `locality`
- `confidence`: 0 to 1. Starts at 1.0 (number), 0.6 (street) or 0.3 (locality) and is reduced for a misspelt street or different street type, a street number found only with a different letter suffix (12 for 12A), an unknown unit, a suburb/city that disagrees, a state that disagrees, a postcode that disagrees when the suburb/city does not confirm the match, or an equally good match more than 1 km away
- `match`: `street_number`, `unit`, `street`, `locality`, `region` (the state, Australia) and `postcode`, each `true` (agrees), `false` (disagrees) or `null` (not in the query)

The result is the best available, not necessarily a correct one: check `confidence` and `match` before storing the coordinates.

```sh
curl "https://api.addressable.dev/v2/geocode?api_key=YOUR_API_KEY&country_code=NZ&q=Level+2,+24+Marine+Parade,+Bluff+Hill,+Napier+4110"
```

## Reverse Geocode

Convert coordinates into the nearest address.

`GET https://api.addressable.dev/v2/reverse`

| Parameter | Required | Description | Example |
| --- | --- | --- | --- |
| `lat` | Yes | Latitude | `-36.849304` |
| `lon` | Yes | Longitude | `174.765469` |
| `api_key` | Yes | Your API key | `YOUR_API_KEY` |

The response includes a `country_code` field indicating which country the coordinates resolved to, followed by the same fields as autocomplete for that country.

Successful response (NZ):

```json
[{"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):

```json
[{"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):

```json
[{"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"}]
```

Successful response (EE):

```json
[{"country_code":"EE","street_number":"19-89","street":"J. Koorti tn","locality":"Lasnamäe linnaosa","postcode":"13623","district":"Harju maakond","municipality":"Tallinn","lon":"24.831852","lat":"59.441451","formatted":"J. Koorti tn 19-89, 13623 Lasnamäe linnaosa"}]
```

Successful response (FI):

```json
[{"country_code":"FI","street_number":"1","street":"Mannerheimintie","locality":"Helsinki","postcode":"00100","municipality":"Helsinki","lon":"24.940524","lat":"60.171260","formatted":"Mannerheimintie 1, 00100 Helsinki"}]
```

Successful response (DK):

```json
[{"country_code":"DK","street_number":"1","street":"Rådhuspladsen","locality":"København V","postcode":"1550","region":"Region Hovedstaden","municipality":"København","lon":"12.566679","lat":"55.675941","formatted":"Rådhuspladsen 1, 1550 København V"}]
```

Successful response (IS):

```json
[{"country_code":"IS","street_number":"1","street":"Laugavegur","locality":"Reykjavík","postcode":"101","region":null,"municipality":"Reykjavík","lon":"-21.937800","lat":"64.146600","formatted":"Laugavegur 1, 101 Reykjavík"}]
```

Successful response (NO):

```json
[{"country_code":"NO","street_number":"22","street":"Karl Johans Gate","locality":"Oslo","postcode":"0026","region":null,"municipality":"Oslo","lon":"10.749100","lat":"59.913700","formatted":"Karl Johans Gate 22, 0026 Oslo"}]
```

Successful response (FO):

```json
[{"country_code":"FO","street_number":"1","street":"Bryggjubakki","locality":"Tórshavn","postcode":"100","region":null,"municipality":"Tórshavnar kommuna","lon":"-6.769000","lat":"62.012100","formatted":"Bryggjubakki 1, 100 Tórshavn"}]
```

Successful response (GL):

```json
[{"country_code":"GL","street_number":"1","street":"Aqqusinersuaq","locality":"Nuuk","postcode":"3900","region":null,"municipality":"Kommuneqarfik Sermersooq","lon":"-51.721400","lat":"64.183300","formatted":"Aqqusinersuaq 1, 3900 Nuuk"}]
```

Successful response (CA):

```json
[{"country_code":"CA","unit":null,"street_number":"350","street":"Sparks Street","locality":"Ottawa","region":"ON","postcode":"K1R 7S8","lon":"-75.70032","lat":"45.42111","formatted":"350 Sparks Street, Ottawa, ON K1R 7S8"}]
```

```sh
curl "https://api.addressable.dev/v2/reverse?api_key=YOUR_API_KEY&lat=-36.849304&lon=174.765469"
```

## Profile

Check identity or subscription expiry.

`GET https://api.addressable.dev/v2/profile`

| Parameter | Required | Description | Example |
| --- | --- | --- | --- |
| `api_key` | Yes | Your API key | `YOUR_API_KEY` |

Successful response:

```json
{"email":"team@addressable.dev","subscription_expires_on":"2025-01-01"}
```

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

## Error responses

Errors are JSON of the form `{"errors":[{"error_type":"request","message":"..."}]}`.

| HTTP code | Messages |
| --- | --- |
| 400 | `Query parameter q is required` |
| 401 | `API key invalid` |
| 406 | `Unrecognised country code`, `Invalid type value`, `Invalid max_results value`, `Coordinates not within expected country bounds`, `Lon can't be blank`, `Lat can't be blank`, `Lat must be between -90 and 90`, `Lon must be between -180 and 180` |
| 429 | `Rate limit exceeded` |

## Rate limits

Requests are rate limited per calendar day (UTC).

| Account type | Daily limit |
| --- | --- |
| Free | 100 requests |
| Addressable Small | 5,000 requests |
| Addressable Large | 30,000 requests |

When the limit is exceeded, requests return a 429 response. Pricing: https://www.addressable.dev/pages/pricing