# Addressable

> Addressable is a REST API for address autocomplete and reverse geocoding, built on official open address data for Australia, Belgium, Canada, Denmark, Estonia, Finland, Faroe Islands, Greenland, Iceland, Lithuania, Latvia, Norway, New Zealand, and Sweden. Every request is an authenticated `GET` to `https://api.addressable.dev` with an `api_key` query parameter and returns JSON. CORS is enabled.

Key facts for agents writing an integration:

- Keep the API key on the server. Proxy browser requests through your own backend rather than putting `api_key` in client-side code.
- Only call autocomplete once the user has typed at least 3 characters, and debounce input by about 300ms. Requests are limited per calendar day (UTC): free accounts get 100 requests/day, Addressable Small 5,000/day, Addressable Large 30,000/day. Going over returns HTTP 429.
- `country_code` (ISO 3166 alpha-2, one of AU, BE, CA, DK, EE, FI, FO, GL, IS, LT, LV, NO, NZ, SE) is required for autocomplete. Reverse geocoding works out the country from `lat`/`lon` and returns `country_code` in each result.
- Each result has a `formatted` string. Every other field can be `null`, depending on how precise the match is. A query with no matches returns HTTP 200 and `[]`.
- Result fields differ by country. Check the documentation for the country you need.

## API

- [OpenAPI 3.0 spec](https://www.addressable.dev/openapi.yml): the machine-readable contract. Generate clients from this.
- [Documentation](https://www.addressable.dev/pages/documentation.md): endpoints, parameters, a sample response for each country, error codes and rate limits
- Autocomplete: `GET /v2/autocomplete?q=&country_code=&api_key=`, with optional `type` (number,street,locality) and `max_results` (1-10, default 5)
- Reverse geocode: `GET /v2/reverse?lat=&lon=&api_key=`
- Profile: `GET /v2/profile?api_key=`, which returns the account email and subscription expiry

## Getting started

- [Sign up](https://www.addressable.dev/users/sign_up): free registration. Your API key is on the account page.
- [Pricing](https://www.addressable.dev/pages/pricing): plans, daily limits and currencies

## Data coverage

- [Countries](https://www.addressable.dev/countries): supported countries and data sources, with data freshness
- [Attribution](https://www.addressable.dev/pages/attribution): source and licence attribution for each country

## Optional

- [Swagger UI](https://www.addressable.dev/pages/swagger-ui): interactive explorer for the OpenAPI spec
- [Redoc](https://www.addressable.dev/pages/redoc): rendered OpenAPI reference
- [News](https://www.addressable.dev/pages/news): data releases and country launches
- [Terms](https://www.addressable.dev/pages/terms): includes "not for resale"
- [Privacy](https://www.addressable.dev/pages/privacy)