Common configurations when setting up Smarty's Address Autocomplete
Address autocomplete might seem simple on the surface—type an address and get suggestions.
However, for developers (or non-developers) looking to create exceptional user experiences, the real power lies in customization. Whether you're building forms for a specific regional audience, managing multiple locations, or handling complex address structures, Smarty's Address Autocomplete API offers granular control beyond the default setup over how addresses are suggested and displayed.
This guide explores the key customization options available through Smarty's SDK, from basic filtering to advanced geolocation preferences. Here’s what you’ll learn:
| Try Us Address Verification | Try US Address Autocomplete | Try International Address Autocomplete |
|---|---|---|
- Where to put your parameters
- Secret–already there–parameters
- How to limit displayed results to a geographic area
- How to exclude a geographic area from displayed results
- Limit the number of results that display
- Display more addresses than just the USPS database
- Caveat if you are using an SDK (Software development kit)
Let's begin.
Where to put your parameters
If you've already got the US Autocomplete API connected and running on your site, you'll just want to look for the code block that’s actually making the API call. It may or may not look like this (we can’t read your code from here):
const sendLookupRequest = async (searchValue, selected = "") => {
const params = new URLSearchParams({
key: settings.embeddedKey,
search: searchValue,
selected
});
You'll want to add your additional parameters between the "search: searchValue," line and the "selected" line within this block.
Secret-already there-parameters
It's worth noting that several parameters aren't listed with the basic autocomplete tool but are, in fact, being referenced behind the scenes. If you want to change these from the default, you'll need to include them in your API call and then give them a new value. These include:
max_results
prefer_ratio
prefer_geolocation
source
The max_results parameter defaults to 10 address results. So, even without adding the "max_results: 10" parameter, you'll only see 10 results on your form.
The prefer_ratio parameter defaults to 100, meaning that 100% of the results displayed will be from your preferred list. For example, if you set your autocomplete to prefer addresses within a state, 100% of the results (as long as there are enough) will be within that preferred state. However, if it’s set to 50, only the first half of the results will be in the preferred state.
The prefer_geolocation parameter defaults to the city where the sender's IP address is located. It uses the sender's IP address (IPv4 only) to determine the location and then automatically adds the city and state to the prefer_cities value. This parameter takes precedence over other “_include” or “_exclude” parameters, meaning that if it is not set to none, you may see addresses from the customer's area when you may not desire them. More on that in a moment.
The source parameter defaults to postal addresses. Smarty offers 20 million non-USPS/non-postal addresses that you can include in your autocomplete, but by default, the source is set to include only addresses in the USPS database.
How to limit displayed results to a geographic area
There are seven parameters that you can use to limit the results that show up in your address autocomplete to a specific area. Here they are:
include_only_cities
include_only_states
include_only_zip_codes
prefer_cities
prefer_states
prefer_zip_codes
prefer_geolocation
Include parameters
The top three "include" parameters ensure that ONLY addresses from the selected options are listed. For example, if I only want Kentucky addresses to be offered to my users, I would add the following parameter:
include_only_states: "KY",
If I want to include several states, I list them with a semicolon between each state, for example: "KY;TN;AR".
The ZIP Code parameter is the same, with the ZIP Codes being separated by semicolons.
include_only_zip_codes: "90210;06504",
Things are a little different with city rules. This field must contain a state after the list of cities, as shown below. Another important note is that you should NOT list a state mentioned within this field in the “include_only_states” field, as it takes precedence over this field.
include_only_cities: "DENVER,AURORA,CO;OMAHA,NE",
List the cities separated by commas, followed by the state they're in. If you have multiple states with cities, separate each one with a semicolon.
If you want to use any "include" or "exclude" parameters, you'll also need to add the "prefer_geolocation" parameter and ensure that it’s set to "none".
Prefer parameters
The four prefer parameters prioritize addresses that meet certain criteria. For example, if there is a "123 Second Street" in Kentucky and a "123 Second Street" in Idaho, these prefer parameters will determine which one is shown first.
As mentioned earlier, the "prefer_geolocation" parameter is on by default, prioritizing addresses closest to the user's IP location. If you want to use any "include" or "exclude" parameters or the "prefer_zip_codes" parameter, you'll ALSO need to add the "prefer_geolocation" parameter and ensure that it’s set to "none".
Setting the preferred state is the same as the “include_only_state” parameter in how it's implemented, but it’ll still show addresses outside of the preferred area if they’re applicable. For example:
prefer_states: "UT;ID;MT",
As mentioned in section 2 above, the “prefer_ratio” parameter will heavily impact the results of all "prefer" parameters. The “prefer_ratio” parameter defaults to 100, meaning 100% of the results displayed will be from your preferred list.
For example, if you have set your autocomplete to prefer addresses within Delaware, 100% of the results (as long as there are enough) will be within Delaware as long as there are 10 addresses in Delaware that match. However, if it’s set to 50, only the first half of the results will be in the preferred state.
How to exclude a geographic area from displayed results
There’s only one parameter that’s specifically focused on preventing certain areas from entering the autocomplete results, and it’s only at the state level.
exclude_states: "UT;CA;NV",
This is handy if you have fewer states that you're excluding than including.
The “prefer_geolocation” parameter MUST be set to "none" if the customer's current location is in a state specified in this parameter; otherwise, the user will see addresses from their current location.
Limit the number of results that display
As mentioned in section 2 above, the “max_results” parameter is automatically set to 10. If you'd like to display less than 10, simply add "max_results" to your parameters and input the number you'd like to display. For example:
max_results: 5,
This can be any number between 1 and 10.
Display more addresses than just the USPS database
The USPS has around 190 million deliverable addresses listed in its database. Smarty includes an additional 20 million addresses that are deliverable by non-USPS services but unrecognized by the USPS.
There are a lot of reasons an address might be considered "non-USPS," including new builds that the USPS hasn't added yet: the address being too remote so the USPS doesn’t route to it, or the address is the address of a location but not a building, like a cell tower.
If you want to include these non-USPS addresses in your autocomplete results, simply add the "source" parameter and set it to "all" like this:
source: "all",
This will bump the potential addresses from 190 million to 210 million.
Caveat if you are using an SDK (Software development kit)
While the principles mentioned above are sound, there’s one other thing to consider if you’re using an SDK.
The names of the parameters will be formatted differently depending on the SDK you’re using.
For example, the Javascript SDK parameters will be in "camel case" (meaning no spaces, and capitalized all words following the first one) instead of "snake_case" (underscores replace meaning spaces), so the "exclude_states" parameter will be listed as "excludeStates" instead.
The rules may be slightly different depending on what SDK you're using, so you'll want to be sure you follow the correct formatting.
If you want more information on parameters and details on using the autocomplete API, you can visit the documentation page for the US Autocomplete Pro API.