Address Suggestions and Candidates

The "Fast Lane" Answer

At SmartyStreets, we specialize in address validation. Our goal is to take the input you give us and match it to the best possible address candidate. A candidate is what you get back from our system after you submit an address for validation. Candidates will always be valid addresses. As you enter addresses into a form with our autocomplete feature, we're also able to provide address suggestions as you type. Autocomplete suggestions are based on the street/city/state combination and may or may not be valid addresses. Suggestions are presented to help you fill out the form faster so you can submit the address for validation and get a candidate back.

There are many factors that affect candidates and suggestions, but it's more than we can fit in this Fast Lane answer. For a more in-depth look at what our API gives you, keep reading.

The "Scenic Route" Answer

Multiple Candidates

Sometimes an address will have multiple valid candidates. Here's an example:

Input: 1109 9th Phoenix, AZ Candidate 1: 1109 S 9th Ave, Phoenix AZ 85007-3646 Candidate 2: 1109 N 9th St, Phoenix AZ 85007-2734

There are two address matches (candidates) on that street: one on the north, the other on the south. Both are valid addresses, so you'd need to present these two options back to the user. Remember: Customers know their addresses better than any computer will.

Keep in mind that addresses are very messy. Don't make too many assumptions about how the address might be wrong. If our system tells you an address is invalid, present that to the user and ask them.

Address Suggestions

If you're using our jQuery plugin with your website forms, getting address suggestions is easy: our autocomplete feature is built into the plugin and gives suggestions as the user types.

You can also use the autocomplete feature without the jQuery plugin. You'll just need to build a request to the Autocomplete API.

With our US Autocomplete API, you can filter address suggestions based on cities and/or states. That way, if you only serve customers in, say, Montana, you can restrict the autocomplete to only show Montana address suggestions.

More Aggressive Address Suggestions

If you need a more aggressive approach to getting address suggestions, you can create a work-around using our API. For example, if you have a sample address and want to see what valid addresses might be around it, you could send a batch request with 1–100 North Main and then display the results. That would allow you to present suggestions to your users in the event that the requested address is invalid. If you submit 100 North Main #1, 100 North Main #2... (or a, b, c), you can also return secondary (apartment) number suggestions to your users. (Note: Keep in mind that each request you send to our API counts as a lookup.)

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff