My Geocode

Guides

Build a "did you mean" suggestion box with autocomplete

· 3 min read · My Geocode · #autocomplete#ux#forms#addresses

A "did you mean" box works best when it appears quietly, offers a short list, and gets out of the way if none of the suggestions fit. The autocomplete endpoint is built for exactly that pattern.

The request

GET /v1/autocomplete?q=Baker Stret&limit=4
{
  "status": "ok",
  "query": "Baker Stret",
  "suggestions": [
    {"text": "Baker Street, London, UK", "place_id": "abc123"},
    {"text": "Baker Street, York, UK", "place_id": "abc789"}
  ]
}

Note that a typo like "Stret" in the query does not prevent reasonable suggestions from coming back, since the endpoint is built to work with imperfect input, which is the whole point of a suggestion box in the first place.

A second example: no suggestions at all

Not every query, typo or not, produces a useful match.

GET /v1/autocomplete?q=Zzqxlm Nonexistent Rd&limit=4
{
  "status": "ok",
  "query": "Zzqxlm Nonexistent Rd",
  "suggestions": []
}

An empty suggestions array here is a correct response, not a sign that something went wrong with the request. Design the box to disappear quietly when this happens, rather than showing an empty dropdown or a visible error state for input that simply has no good match.

Displaying the list

Show the text field from each suggestion as the visible label, and keep the place_id attached to whichever one gets clicked, since that identifier is what you pass forward to resolve the full address afterward rather than re-parsing the display text.

Keeping it optional

The most important part of this pattern, especially on a site with no client-side JavaScript running the interaction, is that the field still accepts a typed address directly on form submission, whether or not a suggestion was clicked. A suggestion box that blocks submission until one of its options is selected turns a helpful nudge into a hard requirement, and any address that legitimately is not in the suggestion list becomes impossible to submit.

An edge case worth testing

Addresses written in a script other than the one your suggestion box was mainly tested with, or transliterated place names, are a real part of most address databases and deserve the same "fall back to plain text" treatment as any other unmatched query. Do not assume a lack of suggestions for unusual input means the input itself is invalid, since the correct response is often just to let the customer submit exactly what they typed.

Limiting requests

Set limit to a small number, three to five is usually enough for a suggestion box, since a longer list defeats the purpose of a quick visual scan. Debounce the calls so a request only fires after a short pause in typing, keeping the total request count for a session low.

Cost per session

A typical address field might trigger a handful of autocomplete calls per visitor as they type and correct themselves, each one request. That is a small fraction of the 2,500 free requests a day included with every key, or available from a single address without one, even on a form with meaningful traffic.

A well-built suggestion box catches typos quietly and steps aside for anything it does not recognize. Full field definitions are on the address autocomplete docs.

More in Guides