Address autocomplete (Photon)

Address questions offer search-as-you-type autocomplete. The backend proxies all geocoding through GET /public/v1/geocode — the embed never talks to the geocoder directly — backed by Photon, komoot’s OpenStreetMap-based autocomplete geocoder.

The public-instance caveat

The default PHOTON_BASE_URL is Photon’s public instance, https://photon.komoot.io. That is a fair-use community service — fine for evaluation, but self-host Photon for production traffic:

# add to docker-compose.yml
photon:
  image: rtuszik/photon-docker:latest   # community image; see Photon's README
  environment:
    - COUNTRY_CODE=us                   # downloads a country extract on first start
  volumes:
    - photon_data:/photon/photon_data

Then set PHOTON_BASE_URL=http://photon:2322 on the backend service (and add photon_data: to the compose file’s volumes).

Failure is silent by design

If the geocoder is down, slow (the proxy allows 2 seconds), or returns garbage, the endpoint returns an empty suggestion list and the embed’s suggestion dropdown simply doesn’t appear — manual address entry always works. A dead geocoder can degrade the experience but never break a form.

How the proxy behaves

Worth knowing when debugging:

q must be 3–200 characters; suggestions only start at the third typed character (the embed also debounces 300 ms).
limit defaults to 5, clamped to 1–10.
country (an ISO alpha-2 code, taken from the address question’s country field) is applied as a local filter on the proxy — Photon is over-queried (up to 3× the limit, max 30) and the results filtered by country code, because Photon’s own API doesn’t take a country parameter this way.
Responses are normalized to { line1, city, state, postalCode, country, label } with empty strings for missing parts; US state names are normalized to two-letter USPS codes.
The endpoint has its own rate-limit bucket (burst 10, 2/s per IP), so autocomplete abuse can’t starve the rest of the API.