What to show when autocomplete has no suggestions

Someone starts typing an address into your form. The suggestions list is empty. Should the helper text ask them to keep typing, add a ZIP code, or check what they entered?

An empty array doesn't answer that. Address autocomplete in API 2.0.0 includes a reason field so your interface can give a useful next step.

For a US address form scoped to Denver, a request early in typing might be:

GET /address?q=m&city=Denver&state=CO&country=US

The response includes this excerpt:

{
  "q": "m",
  "reason": "more_input",
  "addresses": []
}

There's no suggestion to display yet. "Keep typing your street address" is enough. You can use the other reasons to choose similarly small hints:

• more_input means more address text is needed. Ask the person to keep typing.
• missing_context means the search needs a location. Ask for a ZIP code, or a city and state.
• no_matches means a completed search found no suggestions. Offer a spelling check or manual entry.
• null accompanies returned suggestions. Clear the hint and show the list.

Pass the form's ZIP as postal, or its city and state as city and state. The reason is part of the autocomplete response. You don't need deep=true to receive it.

Treat reason as an optional, open string. Older responses may omit it, and your interface should tolerate an unfamiliar value. Keep a generic empty-list message as the fallback instead of requiring every response to match one of these strings.

A failed search is a separate case. HTTP 503 with service_unavailable means suggestions are temporarily unavailable. Show that state separately and leave the typed address editable.

These hints describe the search. no_matches doesn't establish that an address doesn't exist, and receiving suggestions doesn't establish postal deliverability. Use the Address API reference to wire the hints into your form without turning an empty dropdown into an invalid-address error.