---
title: "Find Address"
method: GET
path: "/autocomplete/addresses"
tags: ["Address Search"]
---

# Find Address

`GET /autocomplete/addresses`

## Request

- Base URL: `https://api.addresszen.com/v1`
- URL: `https://api.addresszen.com/v1/autocomplete/addresses`
- Auth: HTTP bearer

Returns address suggestions for a partial address, ranked by relevance. Use it to autofill an address form as the user types.

A suggestion is a display label and an `id`, not a full address. Retrieve the address with a second request to `/autocomplete/addresses/{id}/usa`. That second request is the one which decrements your lookup balance.

Autocomplete is not a free standalone resource. We rate limit, then suspend, keys that autocomplete without resolving suggestions.

Our address autocomplete JavaScript libraries add this to a form without calling the API directly.

## Coverage

Each search runs in one country, selected with `context`. A missing or unrecognized `context` falls back to your account default. Results come from the datasets enabled on your key: USPS Zip+4 for the US and its territories, and the country datasets you license elsewhere. Where a key has more than one dataset for a country, `dataset` narrows the search.

## Filters

Filters restrict results, e.g. `state_code=NY` searches New York only. A filter which matches no address returns an empty set. An unrecognized filter name is ignored. Neither affects your lookup balance.

Filters combine with `AND` logic, so `state_code=CA&city=San Francisco` requires both. A comma-separated value combines terms for one filter, e.g. `postal_code_3=11225,11226,11238` accepts any of the three ZIP codes. Unless a parameter states otherwise, every filter takes multiple terms. The maximum is 10 filter terms.

## Address bias

Bias terms carry the `bias_` prefix and promote addresses rather than restricting the set, so unmatched addresses still appear, lower down. For example, `bias_state_code=NY,NJ` favors addresses in New York and New Jersey, `bias_lonlat` favors addresses near a point. Invalid bias terms have no effect. Multiple bias terms are allowed unless stated otherwise, with a combined maximum of 5.

## Suggestion format

The suggestion string is subject to change. Present it to the user as it arrives rather than parsing it.

## Rate limiting and cost

The default rate limit is 3,000 requests per 5 minutes, counted per API key and IP address. The `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers report the current window.

Autocomplete requests do not draw on your balance. Resolving a suggestion to a full address does.

## Query parameters

- `api_key` string
- `query` string
- `dataset` Dataset[]
- `context` string
- `limit` integer
- `bias_lonlat` string
- `bias_ip` 'true'
- `box` string
- `postal_code` string
- `postal_code_2` string
- `postal_code_3` string
- `city` string
- `state` string
- `state_code` string
- `bias_postal_code` string
- `bias_postal_code_2` string
- `bias_postal_code_3` string
- `bias_city` string
- `bias_state` string
- `bias_state_code` string
- `is_pobox` 'true' | 'false'
- `is_business` 'true' | 'false'

## Response `200`

Success

- AutocompleteResponse
  - `result` object, required
    - `hits` AddressSuggestion[], required
      - `id` string, required: Global unique internally generated identifier for an address
      - `suggestion` string, required: Address Suggestion to be displayed to the user
      - `urls` object, required: Always an empty object (`{}`). Retrieve the full address with `id`
  - `code` 2000, required
  - `message` 'Success', required

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/addresszen/apis/api-reference.md) · [All operations](https://skmtc.dev/addresszen/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/addresszen/apis/api-reference/revisions/cac119db15c0?raw)