Adding address autocomplete to a web form

Why autocomplete the address

A typed address is where most delivery errors start: a missing box, a street spelled two ways, a postcode from the next town. Suggesting official addresses while the customer types removes the mistake before it is stored.

It also shortens the form: one field instead of five, filled in a few keystrokes.

When to send the search

• Wait for two or three characters: shorter input matches too much to help.
• Wait about 200 milliseconds after the last keystroke, so a fast typist sends one search rather than ten.
• Cancel the previous request when a new one leaves, so an old answer never replaces a newer one.
• Show five to eight suggestions at most.

What to do with the chosen suggestion

Fill the structured fields (street, number, box, postcode, locality) from the suggestion, not from the text typed, and keep them editable.

Store the coordinates and the official identifier with the address: they let you compare two addresses later without comparing spellings.

When the building has boxes and the suggestion carries none, ask for the box in its own field rather than letting it be typed after the street.

Keyboard and screen readers

• The arrow keys move through the suggestions, Enter picks one, Escape closes the list.
• Follow the ARIA combobox pattern: the input has the combobox role, the list the listbox role, and aria-activedescendant follows the highlighted suggestion.
• Announce the number of suggestions in a live region.
• Never block manual entry: a brand new building may not be in the reference yet.

Keep the API key on your server

The key that authenticates the API must never reach the browser, where anyone can read it. Send the search to your own backend, which adds the key and forwards the call.

The same backend can cache the most frequent beginnings of a search and enforce your own limits per visitor.

Billing that follows the typing

Many address services bill each call or each selected address. Addrly bills its autocomplete per typing session: the keystrokes of one lookup count as one request, so the debounce above saves latency rather than money.

Frequently asked questions