Webinar
Smarty

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:

URL components Values Notes
Scheme https NOTE: Non-secure http requests are not supported
Hostname us-autocomplete.api.smarty.com
Path /suggest
Query string ?key=YOUR+EMBEDDED+KEY+HERE Using "secret key" authentication will result in a 401 error. Use "embedded key" authentication instead. 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 methods are supported by this API:

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:

Header Description Example
Host The Host request header field specifies the internet host and port number of the resource being requested Host: us-autocomplete.api.smarty.com

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.
prefer_ratio decimal(10,9) 0.333333333 Specifies the percentage of address suggestions that should be from preferred cities/states. Expressed as a decimal value, range [0, 1] (input out of bounds is adjusted). 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. (If the request to the Autocomplete API goes through a proxy, you will need to set an X-Forwarded-For header specifying the user's IP address.)
geolocate_precision string city If 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 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 embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded 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

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.