US Autocomplete API

This page describes how to use the SmartyStreets US Autocomplete API. (Free testing accounts available)


  1. HTTP Request
    1. URL Composition
    2. Request Methods
    3. Request Headers
    4. Input Fields
  2. HTTP Response
    1. Status Codes and Results
    2. Example Response
  3. Advanced Concepts
    1. Filtering
    2. Preference
  4. Supplementary Material
    1. Subscription Usage
    2. SSL/TLS Information
    3. Try the demo

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL (with linebreaks for readability):

Here is a more granular examination of the example above:

URL Components Values Notes
Scheme https NOTE: Non-secure http requests are not supported
Path /suggest
Query String ?auth-id=8d497be5-e211-4949-a18f-0bfd1d9970d3&auth-token=th4hargQiuyG7w7L7xfO Authentication information, inputs, etc. Additional query string parameters are introduced in the next section.

For additional information about URLs, please read our article about URL components.

HTTP Request: Supported Methods/Verbs

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests." Other common methods are PUT, POST, and DELETE.

The following method is supported by this API:

Note: When calling any of our APIs using "Website Key" authentication, only the HTTP GET method is allowed. With "Secret Key" authentication, both HTTP GET and POST methods are allowed.

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP Request: Headers

You must include the following required HTTP headers in all requests:

Header Description Example
Host The Host request header field specifies the internet host and port number of the resource being requested Host:

Input Fields

Name Type Default Value Description
prefix string (empty) Required. The part of the address that has already been typed. Maximum length is 128 bytes.
suggestions integer 10 Maximum number of address suggestions, range [1, 10]. Default is 10.
city_filter string (empty) A list of city names, separated by commas, to which to limit the results. See filtering for more information.
state_filter string (empty) A list of state names (2-letter abbreviations), separated by commas, to which to limit the results. See filtering for more information.
prefer string (empty) A list of cities/states to prefer at the top of the results. See preferencing for more information.
geolocate bool true Whether to prefer address suggestions in the user's city and state, based on their IP address.
geolocate_precision string city If the geolocate field is set to truethen setting this field to city causes the geolocated results that bubble up to the top of the response to be from the city/state corresponding to the sender's IP address. Setting this field to state causes results from the sender's entire state to be preferred.

HTTP Response: Status Codes and Results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Status Code Response and Explanation
401 Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402 Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400 Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.
422 Unprocessable Entity (Unsuitable Payload): The value of the prefix input parameter was too long and could not be processed.
429 Too Many Requests: When using public "website key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use "website key" authentication, you can avoid this error by adding your IP address as an authorized host for the website key in question.
200 OK (success!): The response body is a JSON object with a suggestions array containing suggestions based on the supplied input parameters.

Example Response

curl -v '

The resulting JSON contains a list of suggestions, each containing the concatenated address suggestion in a field called

  • text well as its components...

  • street_line,
  • city, and
  • state

...which you can use to fill form fields. Here's an example of the actual response JSON:

	"suggestions": [
			"text": "123 Main Rd, Abbot ME",
			"street_line": "123 Main Rd",
			"city": "Abbot",
			"state": "ME"
		// 9 more suggestions truncated...

Be aware that autocomplete suggestions do not include a ZIP Code because they are not necessarily valid. Suggested addresses must still be submitted to our verification endpoint.


To limit address autocomplete suggestions to a set of cities and/or states, you can use filters. A filter is a comma-separated list of cities/states. You can specify both city and state filters to limit suggestions to any of those cities in any of those states. Filters tend to override preference strings. Geolocated results and filtered results are not mutually exclusive, so if you want only filtered results, turn off geolocation.

Note: when using state_filter or city_filter, results will not include the state (or city) until after the street is entered.

Sample filters

Restrict suggestions to Hawaii, Alaska, and American Samoa: state_filter=HI,AK,AS

Restrict suggestions to Chicago and Los Angeles: city_filter=Chicago,Los+Angeles


You can have suggestions in certain cities/states bubble to the top of the results by setting a preference string. A preference string consists of a list of cities and states separated by semicolons, with commas between each city and state. To specify a city, a state must also accompany it.

At most, the top 1/3 of results (rounded up) will be preferred.

Sample preference strings

Prefer Las Vegas, NV: prefer=Las+Vegas,NV

Prefer Houston and Spring in TX: prefer=Houston,TX;Spring,TX

Prefer Utah and Minnesota: prefer=UT;MN

Prefer Salt Lake City and Nevada: prefer=Salt+Lake+City,UT;NV

Subscription usage

Beyond ensuring that requests include proper authentication, clients of the Autocomplete API must maintain an active API subscription. At this time, the Autocomplete API does not count against your subscription usage. This policy is subject to change in the future.

SSL/TLS Information

Use Modern Security Software and Cipher Suites
Certificate Authority:
	AddTrust External CA Root
	Fingerprint: 02faf3e291435468607857694df5e45b68851868

Supported Protocols:
	TLS 1.2
	TLS 1.1
	TLS 1.0

Cipher Suites:

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff