US Autocomplete Basic to US Autocomplete migration guide
Purpose
US Autocomplete Basic (us-autocomplete.api.smarty.com) has undergone many updates,
first being replaced by US Autocomplete Pro in 2020, and more recently by US Autocomplete.
This guide is designed to help customers migrate from the US Autocomplete Basic API to the new US Autocomplete API to avoid service disruption once US Autocomplete Basic is sunset.
Migration steps
URL
Change the URL used to access the API.
US Autocomplete Basic:
https://us-autocomplete.api.smarty.com/suggest?US Autocomplete:
https://us-autocomplete.api.smarty.com/v2/lookup?Input parameters
Several input parameters have changed in name and value format. The following table describes these changes and highlights what stayed the same.
| US Autocomplete Basic | US Autocomplete | Comments |
|---|---|---|
prefix |
search |
The value format is identical. |
city_filter |
include_only_cities |
city_filter is a comma-separated list of cities.e.g., chicago,aurora,cleveland
include_only_cities is a list of cities and their state abbreviations,
separated by a semicolon.e.g., chicago,aurora,il;cleveland,oh
|
state_filter |
include_only_states |
state_filter is a comma-separated list of state abbreviations. e.g., il,ohinclude_only_states is a semi-colon list of state abbreviations. e.g., il;oh
|
prefer |
prefer_citiesprefer_states |
prefer can be split into prefer_cities or
prefer_states, depending on your need. prefer is formatted as follows: e.g., Houston,TX;Spring,TXprefer_cities is formatted like include_only_cities as follows:
e.g., houston,spring,tx;denver,coprefer_states is formatted like include_only_states as follows: e.g., tx;nm
|
prefer_ratio |
prefer_ratio |
In Basic, the accepted values are from 0 to 1 as a decimal
number. The default is .33, indicating that the top third of results come
from the prefer parameter.In US Autocomplete, accepted values are integers from 0 to 100.
The default is 100, indicating that all results will be from the
prefer_cities and prefer_states parameters.
|
geolocate |
prefer_geolocation |
geolocate is either true or false prefer_geolocation is either city (equivalent to true) or
none (equivalent to false). The default is city.
|
geolocate_precision |
geolocate_precision is either city or stateUS Autocomplete does not use the geolocate_precision parameter.
Instead, it uses the prefer_geolocation parameter to determine the precision.
It automatically falls back to results from the preferred state if enough results are not
found in the preferred city.
|
Results
The basic JSON format is the same, but the result objects themselves have changed, as well as how to interpret them.
| US Autocomplete Basic | US Autocomplete |
|---|---|
|
|
Aside from the differences in field names, US Autocomplete Basic handles secondaries differently. It will only return a secondary if the user knows it and enters the exact secondary number.
In contrast, US Autocomplete will show a result similar to the following to indicate when there
is a list of secondaries available at this address. Notice "entries": 207
{
"street_line": "1600 Avalon Rd",
"secondary": "Apt",
"city": "Layton",
"state": "UT",
"zipcode": "84041",
"entries": 207,
"source": "postal",
"entry_id": "AbCdEfGhIj"
},
When the end user selects the above address, another call needs to be made to US Autocomplete, which will return the first 100 secondaries associated with that address. See the documentation for how to call US Autocomplete to expand the secondary list using the selected parameter.
Additional features in US Autocomplete
There are many other features available in US Autocomplete that you should consider to enhance the user experience. Consult the US Autocomplete documentation to see a list of these features.