US Autocomplete Pro to US Autocomplete migration guide

Purpose

US Autocomplete Pro (us-autocomplete-pro.api.smarty.com) is being replaced by US Autocomplete (us-autocomplete.api.smarty.com), the next-generation of US Autocomplete solutions by Smarty.

This guide is designed to help customers migrate from the US Autocomplete Pro API to the US Autocomplete API.

Migration steps

URL

Change the URL to access the new API.

US Autocomplete Pro

https://us-autocomplete-pro.api.smarty.com/lookup?

US Autocomplete

https://us-autocomplete.api.smarty.com/v2/lookup?

Input parameters

Existing fields will remain unchanged, but migrating to US Autocomplete introduces an additional helpful parameter, "exclude," which lets you customize your result set to ignore specific addresses.

Name	Type	Default value	Description
exclude	string	(empty)	Specify a comma-separated list of address types to exclude from the result set. Options: base-address - Base addresses commercial - Commercial addresses residential - Residential addresses po-box - PO Box addresses military - Military addresses Example: exclude=po-box,military

Results

Migrating to US Autocomplete will still give you access to the result properties found in Pro, but will also provide access to two additional properties:

1. smarty_key
   • This is the SmartyKey for a result with entries=0, meaning it’s a single address that can’t be expanded. See the first result in the example below.
2. entry_id
   • This ID represents a group of addresses with entries > 1, such as a group of secondaries. See the second result in the example below.
   • Use this ID to expand the secondary group by making a subsequent API call with the selected parameter. Example: selected=AhiJ123kLmnOPQrstUvWxyz
   • This replaces the need to build the selected value with address components, which was required with Pro.

{
	"suggestions": [
		{
			"street_line": "123 E 103rd St",
			"secondary": "",
			"city": "Chicago",
			"state": "IL",
			"zipcode": "60628",
			"entries": 1,
			"smarty_key": "12345",
		},
		{
			"street_line": "123 1/2 W Main St",
			"secondary": "",
			"city": "Owosso",
			"state": "MI",
			"zipcode": "48867",
			"entries": 6,
			"entry_id": "AhiJ123kLmnOPQrstUvWxyz",
		}
	]
}
	

Secondary expansion

As discussed in the Results section above, secondary expansion has been simplified in the new version in the following ways.

1. Use entry_id in the selected parameter.
   • Pro: You had to construct the selected value by assembling components together.
   • New: You simply pass the entry_id as the selected value.
2. Secondary groups now expand automatically

In Pro, groups never auto-expanded. As the user narrowed their search, Pro would keep returning a group with a reduced entry count, and you had to make a second call with the selected parameter to actually see the entries inside. The new version expands the group for you on the first call.

Example: Consider the address 2 Rice St Apt, Saugus MA 01906, which has 185 secondary addresses.

User types	Pro returns	New version returns
2 Rice St Apt 1	A group of 89 (all secondaries starting with 1)	The first 10 apartments, starting with 1
2 Rice St Apt 10	A group of 9 (all secondaries starting with 10)	The 9 apartments starting with 10

Impact: Because Pro didn't auto-expand, many GUI widgets were written to make a follow-up call to expand the group — for example, calling again with selected=2 Rice St Apt 1 (89) Saugus MA 01906 to retrieve the first 10 addresses from the group of 89. With the new version, this second call is no longer needed; the apartments are returned on the first call.