Address Autocomplete

Autocomplete addresses during checkout — user selects country, starts typing, and gets structured suggestions (street, city, zip).

This is a paid feature. Usage is tracked per 15-minute interval and billed monthly based on request count.

How It Works

Customer selects country (required)
Starts typing address → debounced API call returns suggestions
Customer clicks a suggestion → full structured address is filled in
Fields street, city, zip, country are auto-populated

SDK Client

// Search suggestions (country is required)
const { suggestions } = await storefront.addresses.autocomplete('Vodickova 12', 'CZ');

// Get full structured address from a suggestion
const address = await storefront.addresses.getDetail(suggestions[0].placeId);
// { street: "Vodičkova 699/30", city: "Praha", zip: "11000", country: "Czechia", countryCode: "CZ", lat, lng }

React Hook

The useAddressAutocomplete hook handles debouncing, caching, and selection out of the box:

import { useAddressAutocomplete } from '@behio/storefront-sdk/react';

function AddressInput() {
  const {
    query,
    setQuery,
    suggestions,
    isLoading,
    select,
    selected,
    isSelecting,
    clear,
  } = useAddressAutocomplete({
    country: 'CZ',       // required — ISO 3166-1 alpha-2
    debounce: 300,        // ms (default: 300)
    minChars: 3,          // min characters before searching (default: 3)
  });

  return (
    <div>
      <input
        value={query}
        onChange={e => setQuery(e.target.value)}
        placeholder="Start typing your address..."
      />

      {isLoading && <div>Searching...</div>}

      {suggestions.length > 0 && (
        <ul>
          {suggestions.map(s => (
            <li key={s.placeId} onClick={() => select(s.placeId)}>
              {s.description}
            </li>
          ))}
        </ul>
      )}

      {selected && (
        <div>
          <p>Street: {selected.street}</p>
          <p>City: {selected.city}</p>
          <p>ZIP: {selected.zip}</p>
          <p>Country: {selected.country}</p>
        </div>
      )}
    </div>
  );
}

Checkout Form Example

Combine with a country selector for a complete checkout address form:

import { useState } from 'react';
import { useAddressAutocomplete } from '@behio/storefront-sdk/react';

function CheckoutAddressForm({ onComplete }) {
  const [country, setCountry] = useState('CZ');
  const { query, setQuery, suggestions, select, selected } = useAddressAutocomplete({
    country,
    debounce: 300,
  });

  // When user selects a suggestion, fill all fields
  const handleSelect = async (placeId: string) => {
    const address = await select(placeId);
    onComplete({
      street: address.street,
      city: address.city,
      zip: address.zip,
      country: address.countryCode,
    });
  };

  return (
    <div>
      <select value={country} onChange={e => setCountry(e.target.value)}>
        <option value="CZ">Czech Republic</option>
        <option value="SK">Slovakia</option>
        <option value="DE">Germany</option>
        <option value="AT">Austria</option>
        <option value="PL">Poland</option>
      </select>

      <input
        value={query}
        onChange={e => setQuery(e.target.value)}
        placeholder="Street address"
      />

      {suggestions.map(s => (
        <div key={s.placeId} onClick={() => handleSelect(s.placeId)}>
          {s.description}
        </div>
      ))}
    </div>
  );
}

Hook Options

Option	Type	Default	Description
`country`	`string`	required	ISO 3166-1 alpha-2 country code
`debounce`	`number`	`300`	Debounce delay in ms
`minChars`	`number`	`3`	Min characters before searching
`enabled`	`boolean`	`true`	Disable the hook

Hook Return

Property	Type	Description
`query`	`string`	Current input value
`setQuery`	`(value: string) => void`	Input onChange handler
`suggestions`	`AddressSuggestion[]`	Google Places suggestions
`isLoading`	`boolean`	Fetching suggestions
`select`	`(placeId: string) => Promise<AddressDetail>`	Select a suggestion
`selected`	`AddressDetail \| null`	Resolved structured address
`isSelecting`	`boolean`	Resolving place detail
`clear`	`() => void`	Reset everything

Address Detail Fields

After calling select():

Field	Type	Example
`street`	`string`	`"Vodičkova 699/30"`
`streetNumber`	`string`	`"699/30"`
`city`	`string`	`"Praha"`
`zip`	`string`	`"11000"`
`country`	`string`	`"Czechia"`
`countryCode`	`string`	`"CZ"`
`formattedAddress`	`string`	`"Vodičkova 699/30, 110 00 Praha 1, Czechia"`
`lat`	`number`	`50.0815`
`lng`	`number`	`14.4243`