My Geocode

Guides

Add address autocomplete to a checkout form

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

Checkout forms fail more often on address fields than on any other field, usually because a customer mistypes a street name or leaves out a unit number. Suggesting real addresses as they type fixes most of that before it becomes a failed delivery.

The autocomplete request

The /v1/autocomplete endpoint takes partial text and a limit on how many suggestions to return. Call it as the customer types, once they have entered a few characters.

GET /v1/autocomplete?q=221B Baker&limit=5
{
  "status": "ok",
  "query": "221B Baker",
  "suggestions": [
    {"text": "221B Baker Street, London, UK", "place_id": "abc123"},
    {"text": "221B Baker Avenue, Springfield", "place_id": "abc124"}
  ]
}

From suggestion to full address

A suggestion is a short label and a place_id, not a full address record. Once the customer picks one, resolve it to a complete address with components and coordinates by passing the suggestion text to /v1/forward. That second call is what fills in the street, city, region, and postal code fields on your form.

GET /v1/forward?q=221B Baker Street, London, UK&limit=1

That second request is where the components object actually appears, since /v1/autocomplete only ever returns a text label and a place_id, never a breakdown of street, city, and postal code. Skipping this step and trying to parse the suggestion text yourself is more fragile than it looks, since formatting varies by country.

Keeping the request count sane

Firing a request on every keystroke adds up fast on a busy checkout page. Debounce the field so a request only goes out after the customer pauses typing for a moment, and skip requests for anything under three or four characters where suggestions are not useful anyway. Each autocomplete call and each follow-up forward geocoding call counts as one request against your daily allowance, so a debounced field on a busy store can still run well within the 2,500 free requests a day included with every key.

Handling no matches

An empty suggestions array is a normal response, not an error. Let the customer keep typing and fall back to a plain text address field if nothing useful comes back after a few characters, rather than blocking form submission on a suggestion being picked.

A mistake worth avoiding

Treating a clicked suggestion as a finished, validated address is a common shortcut that causes trouble later. A customer can select a suggestion and then keep editing the field afterward, changing a house number or adding an apartment number the original suggestion never had. Always resolve the field's final text through /v1/forward at submission time, not just at the moment a suggestion was clicked, so the address you save reflects what actually ended up in the field.

If your checkout form also collects a postal code separately, a quick call to /v1/postcode once the street address resolves is a cheap way to catch a postal code that does not match the rest of the address, before the two are submitted together and cause a shipping mismatch down the line.

Autocomplete does not replace validation, it just narrows the odds of a bad address reaching your order system in the first place. See the address autocomplete docs for the full parameter list before you wire it into your checkout flow.

More in Guides