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.

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 int32Default 10Example 5

bias_lonlat string optional

Bias by Geolocation

Bias search to a geospatial circle determined by an origin and radius in metres. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres]. 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 for the wrapper format.

• result object

  • hits object[]

    • 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

Request

URL

https://api.addresszen.com/v1/autocomplete/addresses?api_key=ak_test&query=1600 Pennsylvania

curl

curl -G 'https://api.addresszen.com/v1/autocomplete/addresses' \
  -d 'api_key=ak_test' \
  --data-urlencode 'query=1600 Pennsylvania'

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

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

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
$response = file_get_contents(
  "https://api.addresszen.com/v1/autocomplete/addresses?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "1600 Pennsylvania",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "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"
}