Local prototype · simulated data

Autocomplete and selection

Suggest addresses as the shopper types, then expand the chosen suggestion into structured fields — including the unit, when the building has several.

The flow

After at least two characters and a short pause (about 150 ms), call GET /v1/autocomplete with the text so far.
Show the suggestions. Cancel any request still in flight when the shopper keeps typing.
When a suggestion is chosen and has_secondaries is true, call GET /v1/addresses/{id} and offer the units.
Fill street, unit, city, state and ZIP from the selected address.

Suggest

cURL

curl "http://localhost:8787/v1/autocomplete?q=350+fifth&limit=3" \
  -H "Authorization: Bearer sk_test_PLACEHOLDER"

JavaScript

// Server-side (Node 18+). Never ship a secret key to a browser.
const res = await fetch("http://localhost:8787/v1/autocomplete?q=350+fifth&limit=3", {
  headers: { Authorization: "Bearer sk_test_PLACEHOLDER" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code);

Python

import requests

res = requests.get(
    "http://localhost:8787/v1/autocomplete",
    params={"q": "350 fifth", "limit": "3"},
    headers={"Authorization": "Bearer sk_test_PLACEHOLDER"},
    timeout=10,
)
res.raise_for_status()
print(res.json())

JSON

{
  "data": [
    {
      "id": "sug_de1d7b18927d",
      "label": "350 Fifth Ave, New York, NY 10118",
      "street_line": "350 Fifth Ave",
      "secondary": null,
      "city": "New York",
      "state": "NY",
      "zip": "10118",
      "has_secondaries": true,
      "secondary_count": 12
    }
  ],
  "meta": {
    "request_id": "req_0000000000000000docs",
    "source": "simulated",
    "billable": false
  }
}

Narrow results when you already know part of the address with state, city or a zip prefix.

Select and pick a unit

Pass a unit prefix in secondary to filter the list as the shopper types a unit number:

cURL

curl "http://localhost:8787/v1/addresses/sug_de1d7b18927d?secondary=suite+2" \
  -H "Authorization: Bearer sk_test_PLACEHOLDER"

JavaScript

// Server-side (Node 18+). Never ship a secret key to a browser.
const res = await fetch("http://localhost:8787/v1/addresses/sug_de1d7b18927d?secondary=suite+2", {
  headers: { Authorization: "Bearer sk_test_PLACEHOLDER" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code);

Python

import requests

res = requests.get(
    "http://localhost:8787/v1/addresses/sug_de1d7b18927d",
    params={"secondary": "suite 2"},
    headers={"Authorization": "Bearer sk_test_PLACEHOLDER"},
    timeout=10,
)
res.raise_for_status()
print(res.json())

JSON

{
  "data": {
    "id": "sug_de1d7b18927d",
    "street_line": "350 Fifth Ave",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "secondaries": [
      "Suite 200",
      "Suite 2100"
    ]
  },
  "meta": {
    "request_id": "req_0000000000000000docs",
    "source": "simulated",
    "billable": false
  }
}

Recommended interaction

Never block manual entry. If suggestions fail or are rate-limited, the form must still work.
Use the browser widget, or follow the WAI-ARIA combobox pattern if you build your own.