US Autocomplete Pro API

This page describes how to use the Smarty US Autocomplete Pro API. (Free testing accounts available.)

Contents

1. Features
   1. Features
2. HTTP request
   1. URL composition
   2. Request methods
   3. Request headers
   4. Input fields
3. HTTP response
   1. Status codes and results
   2. Example response
   3. Secondary number expansion
4. Advanced concepts
   1. Filtering
   2. Preferences
   3. Use cases for filtering and preferences
   4. Alternate cities
5. Supplementary material
   1. Subscription usage
   2. SSL/TLS information
   3. Try the live API

Features

• Returns suggestions that are fully verified USPS addresses.
• Uses fuzzy logic during searching to:
• Allow for missing directionals and street suffixes.
• Allow substitution of street suffixes and secondary designators. E.g., ST is accepted for AVE; APT is accepted for UNIT, etc.
• Allow full or partial spelling of street suffixes and secondary designators. E.g., ST can be spelled as STR or STREET and still match.
• Filters and preferences allow for multiple cities in a single state.
• Provides filter keywords for common state collections such as allstates. See Filtering.
• ZIP Codes are valid filter and preference values.
• Allows searching on alternate cities.

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-pro.api.smarty.com/lookup?
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 address APIs using embedded key authentication, only the HTTP GET method is 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. Common mistakes we see are non-encoded commas, semicolons, and pound signs. Pound signs (#) like in an apartment number (# 409), when properly encoded in a URL, become %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 'https://us-autocomplete-pro.api.smarty.com/lookup?key=YOUR+EMBEDDED+KEY+HERE&search=123+mai&include_only_cities=chicago%2Cil&include_only_states=mi&prefer_states=il' -H 'referer: https://myneatwebsite.com'

The resulting JSON contains a list of suggestions consisting of the following components

• street_line
• secondary
• city
• state
• zipcode
• entries
• source (present only if the source input parameter was specified)

...which you can use to fill form fields. Here's an example of the actual response JSON:

{
	"suggestions": [
		{
			"street_line": "123 E 103rd St",
			"secondary": "",
			"city": "Chicago",
			"state": "IL",
			"zipcode": "60628",
			"entries": 0
		},
		{
			"street_line": "123 E 104th Pl",
			"secondary": "",
			"city": "Chicago",
			"state": "IL",
			"zipcode": "60628",
			"entries": 0
		},
		{
			"street_line": "123 E 111th St",
			"secondary": "",
			"city": "Chicago",
			"state": "IL",
			"zipcode": "60628",
			"entries": 0
		},
		{
			"street_line": "123 E 117th Pl",
			"secondary": "",
			"city": "Chicago",
			"state": "IL",
			"zipcode": "60628",
			"entries": 0
		},
		{
			"street_line": "123 1/2 E Maple Ave",
			"secondary": "Apt A1",
			"city": "Adrian",
			"state": "MI",
			"zipcode": "49221",
			"entries": 1
		},
		{
			"street_line": "123 1/2 N Mitchell St",
			"secondary": "Apt",
			"city": "Cadillac",
			"state": "MI",
			"zipcode": "49601",
			"entries": 2
		},
		{
			"street_line": "123 1/2 S Lafayette St",
			"secondary": "Apt",
			"city": "Greenville",
			"state": "MI",
			"zipcode": "48838",
			"entries": 3
		},
		{
			"street_line": "123 1/2 W Main St",
			"secondary": "Apt",
			"city": "Owosso",
			"state": "MI",
			"zipcode": "48867",
			"entries": 6
		},
		{
			"street_line": "123 11th St",
			"secondary": "",
			"city": "Plainwell",
			"state": "MI",
			"zipcode": "49080",
			"entries": 0
		},
		{
			"street_line": "123 136th Ave",
			"secondary": "",
			"city": "Wayland",
			"state": "MI",
			"zipcode": "49348",
			"entries": 0
		}
	]
}

To assemble the address into a string and better understand the secondary and entries fields, consider the following JavaScript code:

function buildAddress(suggestion) {
	let whiteSpace = "";
	if (suggestion.secondary) {
		if (suggestion.entries > 1) {
			suggestion.secondary += " (" + suggestion.entries + " entries)";
		}
		whiteSpace = " ";
	}
	return suggestion.street_line + whiteSpace + suggestion.secondary + " " + suggestion.city + ", " + suggestion.state + " " + suggestion.zipcode;
}

123 E 103rd St Chicago, IL 60628
123 E 104th Pl Chicago, IL 60628
123 E 111th St Chicago, IL 60628
123 E 117th Pl Chicago, IL 60628
123 1/2 E Maple Ave Apt A1 Adrian, MI 49221
123 1/2 N Mitchell St Apt (2 entries) Cadillac, MI 49601
123 1/2 S Lafayette St Apt (3 entries) Greenville, MI 48838
123 1/2 W Main St Apt (6 entries) Owosso, MI 48867
123 11th St Plainwell, MI 49080
123 136th Ave Wayland, MI 49348

When the entries field value is greater than 1, it indicates that more than one secondary number matches the user input, thus the address is incomplete. Note that some of the addresses in the example above indicate that there are multiple secondary entries that matched the user input.

Secondary number expansion

When building an Autocomplete UI component, you will need to handle the case when a user selects an address with more than one secondary entry such as the suggestion 1042 W Center St Apt (108 entries) Orem UT. In this case the user expects to see 108 addresses with apartment numbers listed.

To accomplish this, the developer uses the selected parameter. The parameter format for the example above would be:

1042 W Center St Apt (108) Orem UT 84057

which is built from the returned suggestion components below as follows:

street_line secondary (entries) city state zipcode

{
	"street_line": "1042 W Center St",
	"secondary": "Apt",
	"city": "Orem",
	"state": "UT",
	"zipcode": "84057",
	"entries": 108
}

The selected parameter tells the API that it needs to return individual entries for this address. Since this address has more than 100 entries, only the first 100 will be returned. The user can reduce the total number of secondaries available by starting to type a secondary number. For example, if the user types 1042 W Center St Apt A it will reduce the number of available secondaries to only those that start with A.

The overall process for the UI to use the selected parameter is as follows:

• User selects an address with multiple entries
• The API is called with:
  • search - the value of the search UI field
  • selected - the selected address in the proper format
• The returned addresses are displayed
• The search UI field is reset with the value of the selected address up to the left parenthesis, with no trailing spaces. This will allow the user to continue typing the secondary number if they choose to narrow the list.

Example logic flow

Based on the example above, the user types:

1042 W Center

which returns suggestions (formatted with the Javascript code shown earlier):

1042 W Center St Apt (108 entries) Orem, UT 84057
1042 W Center St Unit (60 entries) Orem, UT 84057
1042 E Center St Orem, UT 84057
1042 W Center St Alma, MI 48801
... (6 more are returned but not show here)

The user selects the top entry, and since it has multiple entries the UI makes the following API call:

...lookup?search=1042+W+Center&selected=1042+W+Center+St+Apt+(108)+Orem+UT+84057

The API returns the following (formatted with the Javascript code shown earlier):

1042 W Center St Apt A101 Orem, UT 84057
1042 W Center St Apt A102 Orem, UT 84057
1042 W Center St Apt A103 Orem, UT 84057
1042 W Center St Apt A104 Orem, UT 84057
1042 W Center St Apt A105 Orem, UT 84057
... (95 more are returned but not show here)

Finally, the UI sets the search UI field to everything up to the left parenthesis of the address the user selected (without a trailing space). For example:

1042 W Center St Apt

The user can then select an address from the list or can continue typing to narrow the list. Let's say the user types a space followed by A to list only apartments that start with A. The results returned will be:

1042 W Center St Apt A (24 entries) Orem, UT 84057
1042 W Center St Unit (60 entries) Orem, UT 84057
1042 E Center St Orem, UT 84057
1042 W Center St Alma, MI 48801
... (6 more are returned but not show here)

Notice that by typing A it limits the results to only 24 entries. If the user clicks on that line, the API call will look like:

...lookup?search=1042+W+Center+St+Apt+A&selected=1042+W+Center+St+Apt+A+(24)+Orem+UT+84057

The API will return 24 addresses whose secondary value starts with A.

Filtering

To limit autocomplete suggestions to a set of cities and/or states or ZIP Codes, you can use filters expressed in the include_ and exclude_ parameters.

Important filter rules and limitations:

• State values MUST only be two-character state abbreviations.
• ZIP Code values MUST only be five-digit ZIP Codes and are limited to 100 entries.
• include_only_cities and include_only_states fields MAY be used separately or together. Up to 100 cities may be specified.
  It is important to note that each state in include_only_cities should NOT also be in include_only_states as the state field will take precedence over the city field.
• include_only_zip_codes field CANNOT be used with any other _cities or _states fields in include_, exclude_, or prefer_. The prefer_geolocation parameter must NOT be set to city.
• exclude_states CANNOT be used with any include_ fields but MAY be used with prefer_cities and prefer_states fields. The prefer_geolocation parameter MUST be set to none if the customer's current location is in a state specified in this parameter. If it is not set to none, the customer will see addresses from their current location.
• Keywords CONTIGUOUS and ALLSTATES are ONLY supported in include_only_states and MUST be the only value in the field. When keywords are used, include_only_cities must be empty.
  • CONTIGUOUS - The 48 contiguous states + DC
  • ALLSTATES - All 50 states + DC (no territories)

Sample filter strings:

• include_only_cities=DENVER,AURORA,CO;CASPER,WY&include_only_states=UT;MT
• include_only_states=contiguous
• include_only_zip_codes=84660;90210&prefer_geolocation=none
• exclude_states=UT;MT;ID

Preferences

In order to have preferred suggestions bubble to the top of the suggestion list, use Preferences. The preference format is the same as the filter with a few exceptions. (See also Important Filter Rules and Limitations.)

By default, 100% of the results will be preferred. You can adjust this ratio with the prefer_ratio parameter.

If cities are specified, but that action does not result in sufficient suggestions to fill available spots, the API will expand the search to include the whole state.

Important preference rules and limitations:

• prefer_states does NOT support keywords CONTIGUOUS and ALLSTATES.
• prefer_zip_codes CANNOT be used with any other _cities, _states, include_, exclude_, or prefer_ parameters. The prefer_geolocation parameter MUST be set to none.
• prefer_ values that are not compatible with the include_ fields will be ignored.
  • Example: include_only_states=UT&prefer_states=MT is not compatible. In this case, the prefer_states value will be ignored since no MT results will ever be returned.
• prefer_geolocation must NOT be set to city if any _zip_codes parameters are used.

Sample preference strings:

• prefer_cities=SEATTLE,REDMOND,WA;RENO,NV
• prefer_states=CO;OK
• prefer_zip_codes=84660;90210&prefer_geolocation=none

Use cases for filtering and preferences

Case 1: You only sell products to people in specific cities and states.

You need to limit results to only addresses in Chicago and Bloomington, Il, as well as any address in Nebraska. However, you want to have Illinois addresses show in the top half of the search results.

include_only_cities=CHICAGO,BLOOMINGTON,IL&include_only_states=NE&prefer_states=IL&prefer_ratio=50

Case 2: You cannot sell your products in all states.

You are not allowed to sell your product in 3 states, KS, TX, and AK, so you never want to see results from those states. Most of your customers live in New Yok, NY, and in NJ, so you want those to be at the top of the result list.

exclude_states=KS;TX;AK&prefer_cities=NEW YORK,NY&prefer_states=NJ&prefer_geolocation=none

Case 3: You want the top results to be addresses from the customer's own area.

Your website allows customers to search for their own address. To give them a good experience, you want addresses from their city or area to be the top results. This is done using the geolocation feature which uses their public IP address to determine their city, and automatically populate the prefer_cities parameter at runtime.

prefer_geolocation=CITY

Case 4: You only service an area that spans three ZIP Codes.

Your business only provides service to a small geographical area that spans three ZIP Codes, so you only want to return addresses within that area.

include_only_zip_codes=12207;12208;12209&prefer_geolocation=none

Alternate cities

The US Autocomplete Pro API handles alternate cities elegantly. But what does that mean?

The area within a ZIP Code may contain multiple cities. The city where the US Post Office resides for that ZIP Code is typically the default city. The other cities within the ZIP Code area are alternate cities. Addresses within the USPS address data usually contain only default cities, which means if you search for an alternate city in the raw USPS data, it would not be found.

So when we say that the US Autocomplete Pro API handles alternate cities, we mean the following:

If you are searching for an address and you see that address in the results, it likely has the default city name listed. If you start typing a valid alternate city name, the city in the suggestions will change from the default city name to the alternate city name.

If preference or filter strings contain an alternate city name, addresses that fall within that ZIP Code will return that alternate city name in the suggested addresses instead of the default city that is contained within the USPS database.

We mentioned earlier that USPS address data "usually" contains only the default city name. However, there are some addresses in the USPS data where the alternate city is the preferred city for that address and will be returned by default when searching for that address. In these cases, if you start typing the default city name the address will still be returned but with the preferred city name. This is because that particular address would be invalid according to the USPS with the default city name in the address. Clear as mud?

But wait, there's more! The USPS also has a list of alternate cities that are no longer acceptable for use when mailing. An example would be AT & T, which is an alternate city for AURORA, IL 60572, but is no longer acceptable for use when mailing. Let's say you are typing an AURORA address within that ZIP Code and you start typing AT&T for the city name. It will continue to return suggestions but will show AURORA as the city name in the suggestions. This feature allows users, who used to know a city by a particular name, to still be able to find the address despite the fact that the city name is not valid.

Consider the following examples:

Example 1

1. FORT LAUDERDALE, FL is the default city for ZIP Code 33312. It has acceptable alternate city names of DAVIE, FT LAUDERDALE, and LAUDERHILL. It has an unacceptable alternate city of LAUDERDALE ISLES.
2. If you start typing an address in 33312, it will return FORT LAUDERDALE as the city by default. When you get to the city part and start typing DAVIE, the city in the suggestions will change to DAVIE because it is an acceptable alternate city.
3. If you start typing the city name LAUDER, it will continue to return FORT LAUDERDALE because there are two alternate cities that begin with LAUDER (LAUDERHILL and LAUDERDALE ISLES) and it doesn't know which one you want.
4. Keep typing LAUDERH and the city name will change to LAUDERHILL. Or if you type LAUDERD, it will return FORT LAUDERDALE because LAUDERDALE ISLES is not an acceptable city name.
5. If your filter includes DAVIE,FL, any address you find in 33312 will return DAVIE as the city name. If you continue searching for a city other than DAVIE, no results will be returned because the filter will not allow any other city, valid or not, to be returned.

Example 2

1. YARDLEY, PA is an alternate city to MORRISVILLE in ZIP Code 19067. Even though YARDLEY is an alternate city for MORRISVILLE, some addresses within the USPS data list the preferred city of YARDLEY as the default, so those addresses will return YARDLEY as the city.
2. When you are searching for one of these addresses and you start typing the city MORRISVILLE, it will continue to return YARDLEY as the city because even though MORRISVILLE is the default city for that ZIP Code, it is not a valid deliverable city name for that particular address. (There are only a few thousand of these cases in the USPS data.)

Subscription usage

Beyond ensuring that requests include proper authentication, clients of the US Autocomplete Pro API must maintain an active API subscription.

SSL/TLS information

Use modern security software and cipher suites

US Autocomplete Basic API

The previous version of US Autocomplete 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.