US Autocomplete Pro API

This page describes how to use the Smarty (formerly SmartyStreets) 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 Demo

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:

URL Components Values Notes
Scheme https Non-secure http requests are not supported.
Hostname us-autocomplete-pro.api.smarty.com
Path /lookup
Query String ?key=YOUR+EMBEDDED+KEY+HERE 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 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:

Header Description Example
Host The Host request header field specifies the internet host and port number of the resource being requested. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically. Host: us-autocomplete-pro.api.smarty.com
Referer The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser or programming language HTTP libraries will add this header automatically. However some interfaces such as cURL do not, so you may need to add it manually. Referer: https://mycoolwebsite.com

Input Fields

Name Type Default Value Description
max_results integer 10 Maximum number of address suggestions to return; range [1, 10].
include_only_cities string (empty) Limit the results to only those cities and states listed, as well as those in include_only_states.
IMPORTANT: This field must contain a state after the list of cities as shown in the example.
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.
Example: DENVER,AURORA,CO;OMAHA,NE See filtering for more information.
include_only_states string (empty) Limit the results to only those states listed, as well as those listed in include_only_cities.
IMPORTANT: If a state is mentioned in the include_only_cities field, you should NOT include that same state in this field as it will take precedence. Examples: UT;ID;MT or CONTIGUOUS or ALLSTATES See filtering for more information.
include_only_zip_codes string (empty) Limit the results to only those ZIP Codes listed. When this parameter is used, no other _cities, _states parameters can be used.
Note: When using this parameter, the prefer_geolocation parameter must NOT be set to city.
Example: 90210;06504 See filtering for more information.
exclude_states string (empty) Exclude the following states from the results. When this parameter is used, no other include_ parameters may be used.
Note: 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 customer will see addresses from their current location.
Example: SD;ND;MT See filtering for more information.
prefer_cities string (empty) Display suggestions with the listed cities and states at the top of the suggestion list, as well as those listed in prefer_states. Example: DENVER,AURORA,CO;OMAHA,NE See preferencing for more information.
prefer_states string (empty) Display suggestions with the listed states at the top of the suggestion list, as well as those listed in prefer_cities.
Examples: UT;ID;MT See preferencing for more information.
prefer_zip_codes string (empty) Display suggestions with the listed ZIP Codes at the top of the suggestion list. When this parameter is used, no other _cities or _states parameters can be used.
Note: When using this parameter, the prefer_geolocation parameter must NOT be set to city.
See preferencing for more information.
prefer_ratio integer 100 Specifies the percentage of address suggestions that should be preferred and will appear at the top of the suggestion list. Expressed as an integer value, range [0, 100]. See preferencing for more information.
prefer_geolocation string city If omitted or set to city, it uses the sender's IP address (IPv4 only) to determine location, 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 it.
Acceptable values are: empty string (which defaults to city), none, or city.
Notes:
1. If any _zip_codes parameters are used, this parameter must NOT be set to city)
2. If the request to the Autocomplete Pro API goes through a proxy, you will need to set an X-Forwarded-For header specifying the user's IP address.
selected string (empty) Used by UI components to request a list of secondaries (up to 100) for the specified address. See Secondary Number Expansion for usage information.
source string postal Include results from alternate data sources. Allowed values are:
all - will include non-postal addresses in the results
postal - will limit the results to postal addresses only

If this parameter is used, an additional field named source will be returned for each result, which is either postal for postal addresses, or other if the address is from an alternate data source.

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 embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.
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 parameters): Returns errors describing what needs to be corrected.
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. 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 '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;
}
Yields the following:
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.

Ready to get started?