Our US Autocomplete API is a simple HTTP endpoint that can suggest street addresses while a user is still typing. We'd like to show you how it works in its intended context, our Website Plugin, which uses the US Autocomplete API to suggest addresses and our US Street Address API to validate them.
How It Works
The user starts typing their street address into the address form field.
With each keystroke of input, the Website Plugin submits the provided text to the US Autocomplete API.
The US Autocomplete API returns suggestions taken from an index of street-city-state combinations and populates a dropdown right under the user's cursor. At this point the user-input house number hasn't yet been validated against the street-city-state combinations presented.
Once the user recognizes their address among the suggestions in the dropdown menu, they may select it. (Alternatively, the user may manually fill in the form fields, up to the state, which will trigger validation as described in the next step.)
The Website Plugin then sends the selected address (including the house number, street, city, and state) to the US Street Address API, which attempts to verify the address against the authoritative USPS database.
If a match is found, the USPS-formatted, verified address is returned, including the nine-digit ZIP Code. If a match is not found, the plugin presents a pop-up saying "You Entered An Unknown Address."
Why Does the US Autocomplete API Suggest Invalid Addresses?
The house number shown in the Autocomplete suggestions is taken directly from user input, without previous validation, therefore the Autocomplete suggestions are not necessarily valid. In the intended use case for the Website Plugin it is assumed that the user knows their house number, so the validation step described above will produce the desired address. If you try entering a contrived address, the house number probably doesn't exist, so the address will come back as invalid.
What About Subscription Usage?
The final validation by the US Street Address API will count as a single address lookup against your subscription, but the suggestions given by the US Autocomplete API do not count as address lookups; they are free.