Articles

 

Autocomplete

Our Autocomplete API is a simple HTTP endpoint that can suggest street addresses while a user is still typing.

Use of the Autocomplete API is free; it does not count against your subscription usage. Once an address is selected, it’s sent through our US Street Address API to be standardized and verified, which will count as one address lookup. Not every suggested address will be valid, but the only significant part of any suggestion which may be invalid is the primary (house) number. Streets, cities, and states will always be valid combinations.

When we built autocomplete, we designed it around the user's intent, not verification. Instead of trying to validate their input before they’ve finished (and restricting their input to some limited options) we focused on helping the user finalize their intent faster: simply suggest addresses that match their input so far. We recommend that the final verification check happen when they're done typing.

What about ZIP Codes?

There are a few important reasons we don't use ZIP Codes in our autocomplete suggestions:

  • ZIP Codes are not necessary to verify an address.
  • ZIP Codes slow down users with extra information they have to comprehend at every keystroke.
  • ZIP Codes don't aid in the address entry process since they overlap cities and states in one-to-many and many-to-one relationships, so the address must be verified at the end anyway.
  • Only a street, city, and state combination is necessary to verify addresses. By omitting ZIP Code, we encourage good practice of verifying the address, which then fills out the ZIP Code.

Our autocomplete service handles ZIP Codes gracefully, but it does not translate ZIP Codes to cities/states, or vice-versa. We have a ZIP Code API for that.