US Autocomplete Basic API ***DEPRECATED***

This is an older version of US Autocomplete that has been deprecated. If your account has access to it you may continue to use it. We highly recommend using the much improved US Autocomplete Pro API.

NOTE: Because the US Autocomplete Basic 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.

This page describes how to use the Smarty US Autocomplete Basic API.

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

HTTP request: URL composition

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

https://us-autocomplete.api.smarty.com/suggest?
key=YOUR+EMBEDDED+KEY+HERE

Here is a more granular examination of the example above:

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 methods are supported by this API:

• GET (for sending a single input)
• OPTIONS (for "pre-flight" cross-domain requests)

Note: When calling any of our APIs using embedded 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:

Input fields

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.

Example response

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice.

curl -v 'https://us-autocomplete.api.smarty.com/suggest?key=YOUR+EMBEDDED+KEY+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.

By default, up to the top 1/3 of results (rounded up) will be preferred. You can adjust this ratio with the prefer_ratio input field.

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.