# Find Address **GET** `/v1/autocomplete/addresses` 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. ## Example request **URL** ```http https://api.addresszen.com/v1/autocomplete/addresses?api_key=ak_test&query=1600 Pennsylvania ``` **curl** ```bash curl -G 'https://api.addresszen.com/v1/autocomplete/addresses' \ -d 'api_key=ak_test' \ --data-urlencode 'query=1600 Pennsylvania' ``` **JavaScript** ```javascript const response = await fetch( 'https://api.addresszen.com/v1/autocomplete/addresses?' + new URLSearchParams({ api_key: 'ak_test', query: '1600 Pennsylvania', }) ); const { result } = await response.json(); ``` **Python** ```python import requests response = requests.get( "https://api.addresszen.com/v1/autocomplete/addresses", params={ "api_key": "ak_test", "query": "1600 Pennsylvania", }, ) result = response.json()["result"] ``` **Ruby** ```ruby require "net/http" require "json" uri = URI("https://api.addresszen.com/v1/autocomplete/addresses") uri.query = URI.encode_www_form(api_key: "ak_test", query: "1600 Pennsylvania") result = JSON.parse(Net::HTTP.get(uri))["result"] ``` **PHP** ```php "ak_test", "query" => "1600 Pennsylvania", ]) ); $result = json_decode($response, true)["result"]; ``` ## Example response **200 OK** ```json { "result": { "hits": [ { "suggestion": "10 Downing St, Montpelier, VT, 05602", "urls": {}, "id": "usps_V210079628|10||3797" }, { "suggestion": "10 Ten Downing St, Fountain Inn, SC, 29644", "urls": {}, "id": "usps_X219061579|10||5031" }, { "suggestion": "10 Downing St Apt 1, Montpelier, VT, 05602", "urls": {}, "id": "usps_V210079629|10|1|3798" }, { "suggestion": "2100 N Downing St Unit 10, Denver, CO, 80205", "urls": {}, "id": "usps_Z125260298|2100|10|5272" }, { "suggestion": "10 S Downing St, Denver, CO, 80209", "urls": {}, "id": "usps_Z105732754|10||2411" }, { "suggestion": "10 Downing St, Hollister, MO, 65672", "urls": {}, "id": "usps_W112200302|10||5568" }, { "suggestion": "10 Downing St, Greensboro, NC, 27410", "urls": {}, "id": "usps_Y127860601|10||2448" }, { "suggestion": "1 S Downing St Apt 10, Denver, CO, 80209", "urls": {}, "id": "usps_Z105731302|1|10|2440" }, { "suggestion": "1560 N Downing St Apt 10, Denver, CO, 80218", "urls": {}, "id": "usps_Z122881416|1560|10|1538" }, { "suggestion": "2202 N Downing St Apt 10, Denver, CO, 80205", "urls": {}, "id": "usps_Z122964113|2202|10|5264" } ] }, "code": 2000, "message": "Success" } ``` ## Query parameters * `api_key` string optional **API Key** Your unique identifier that allows access to our APIs. Begins `ak_`. Available from your dashboard. Example: `ak_test` * `query` string optional **Address Query** The partial address string entered by the user to autocomplete. Example: `123 main st spring` * `dataset` array optional **Filter by Dataset** Comma-separated list of datasets to search within. Filters results to only include addresses from the specified datasets. Useful for keys with multiple overlapping datasets enabled (e.g. `paf` and `abp`). Example: `usps` * `context` string optional **Context** Limits search results, typically within a country. Example: `USA` * `limit` integer optional **Limit** Specifies the maximum number of records to retrieve. By default the limit is 10. Requesting a larger result set adds latency. Format: `int32` Default: `10` Example: `5` * `bias_lonlat` string optional **Bias by Geolocation** Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`. Uses the format bias\_lonlat=\[longitude],\[latitude],\[radius in meters]. Only one geospatial bias may be provided. Example: `-2.095,57.15,100` * `bias_ip` string optional **Bias by Geolocation of IP** Biases search based on approximate geolocation of IP address. Set `bias_ip=true` to enable. Enum: "true" * `box` string optional **Filter by Bounding Box** Restrict search to a geospatial box determined by the "top-left" and "bottom-right" geolocations. Supply 4 comma separated values ordered `top_left_lon,top_left_lat,bottom_right_lon,bottom_right_lat`. The top-left longitude must be less than the bottom-right longitude, and the top-left latitude greater than the bottom-right latitude. A box which fails either check is ignored. Only one geospatial box can be provided. Example: `-2.096,57.15,-2.095,57.14` * `postal_code` string optional **Filter by postal code** Restrict results to addresses with a matching full postal code. Case, spaces and hyphens are ignored. For US addresses the full postal code is the nine digit ZIP+4 (`941021234`); filter on `postal_code_3` for a five digit ZIP. For UK addresses use `postcode`. Example: `94102-1234` * `postal_code_2` string optional **Filter by postal code prefix** Restrict results to addresses whose postal code starts with the given segment. For US addresses this is the three digit ZIP prefix (sectional center), e.g. `941` for San Francisco. Example: `941` * `postal_code_3` string optional **Filter by short postal code** Restrict results to addresses with a matching short postal code. For US addresses this is the five digit ZIP code. Example: `94102` * `city` string optional **Filter by city** Restrict results to addresses in the named city, town or locality. Case, spaces and accents are ignored, so `San Francisco` and `sanfrancisco` match the same addresses. For UK addresses use `post_town`. Example: `San Francisco` * `state` string optional **Filter by state** Restrict results to addresses in the named state, province or region, e.g. `California`. Case and spaces are ignored. Example: `California` * `state_code` string optional **Filter by state code** Restrict results to addresses with a matching state or region code, e.g. the two letter USPS state abbreviation `CA`. Case is ignored. Example: `CA` * `bias_postal_code` string optional **Bias by postal code** Boost addresses with a matching full postal code (nine digit ZIP+4 for US addresses). Unmatched addresses still appear, ranked lower. Example: `94102-1234` * `bias_postal_code_2` string optional **Bias by postal code prefix** Boost addresses whose postal code starts with the given segment (three digit ZIP prefix for US addresses). Example: `941` * `bias_postal_code_3` string optional **Bias by short postal code** Boost addresses with a matching short postal code (five digit ZIP for US addresses). Example: `94102` * `bias_city` string optional **Bias by city** Boost addresses in the named city, town or locality. Case, spaces and accents are ignored. For UK addresses use `bias_posttown`. Example: `San Francisco` * `bias_state` string optional **Bias by state** Boost addresses in the named state, province or region. Example: `California` * `bias_state_code` string optional **Bias by state code** Boost addresses with a matching state or region code, e.g. `CA`. Example: `CA` * `is_pobox` string optional **Filter by PO Box** `true` restricts results to PO Box addresses; `false` excludes them. For US addresses this is derived from the USPS record type (`P`). Example: `true` Enum: "true", "false" * `is_business` string optional **Filter by business address** `true` restricts results to business addresses; `false` excludes them. For US addresses this is derived from the USPS record type (`F`, a firm record). Example: `true` Enum: "true", "false" ## Response `result` contains a `hits` array of address suggestions. Each suggestion includes an ID for resolving the full address in a follow-up request. The array sits inside the standard `{ result, code, message }` envelope; see the [API reference](/docs/api/api-reference.md) for the wrapper format. * `result` object * `hits` object\[] | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------ | | `id` | string | Global unique internally generated identifier for an address | | `suggestion` | string | Address Suggestion to be displayed to the user | | `urls` | object | Always an empty object (`{}`). Retrieve the full address with `id` |