Documentation

 

US Autocomplete API

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

NOTE: Because the US Autocomplete API relies on the user to know their primary number, the returned suggestions do not necessarily represent valid addresses. These suggestions contain the house number provided as well as a valid street+city+state. Submitting those values to the US Street API will provide the fully validated address if one exists.

Contents

  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):

https://us-autocomplete.api.smartystreets.com/suggest?
auth-id=8d497be5-e211-4949-a18f-0bfd1d9970d3&auth-token=th4hargQiuyG7w7L7xfO

Here is a more granular examination of the example above:

URL ComponentsValuesNotes
SchemehttpsNOTE: Non-secure http requests are not supported
Hostnameus-autocomplete.api.smartystreets.com
Path/suggest
Query String?auth-id=8d497be5-e211-4949-a18f-0bfd1d9970d3&auth-token=th4hargQiuyG7w7L7xfOAuthentication 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:

HeaderDescriptionExample
HostThe Host request header field specifies the internet host and port number of the resource being requestedHost: us-autocomplete.api.smartystreets.com

Input Fields

NameTypeDefault ValueDescription
prefixstring(empty)Required. The part of the address that has already been typed. Maximum length is 128 bytes.
suggestionsinteger10Maximum number of address suggestions, range [1, 10]. Default is 10.
city_filterstring(empty)A list of city names, separated by commas, to which to limit the results. See filtering for more information.
state_filterstring(empty)A list of state names (2-letter abbreviations), separated by commas, to which to limit the results. See filtering for more information.
preferstring(empty)A list of cities/states to prefer at the top of the results. See preferencing for more information.
geolocatebooltrueWhether to prefer address suggestions in the user's city and state, based on their IP address.
geolocate_precisionstringcityIf the geolocate field is set to true then 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 CodeResponse and Explanation
401Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
400Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.
422Unprocessable Entity (Unsuitable Payload): The value of the prefix input parameter was too long and could not be processed.
429Too 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.
200OK (success!): The response body is a JSON object with a suggestions array containing suggestions based on the supplied input parameters.

Example Response

curl -v 'https://us-autocomplete.api.smartystreets.com/suggest?auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR-AUTH-TOKEN-HERE&prefix=123+mai'

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

  • text

...as 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...
    ]
}

NOTE: Because the US Autocomplete API relies on the user to know their primary number, the returned suggestions do not necessarily represent valid addresses. These suggestions contain the house number provided as well as a valid street+city+state. Submitting those values to the US Street API will provide the fully validated address if one exists.

Filtering

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

Preference

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:
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
	TLS_RSA_WITH_AES_128_GCM_SHA256
	TLS_RSA_WITH_AES_256_GCM_SHA384
	TLS_RSA_WITH_AES_128_CBC_SHA256
	TLS_RSA_WITH_AES_128_CBC_SHA
	TLS_RSA_WITH_AES_256_CBC_SHA256
	TLS_RSA_WITH_AES_256_CBC_SHA