const HOST = "https://autocomplete.search.hereapi.com/v1/autocomplete";
const API_KEY = process.env.HERE_API_KEY;   // proxy this in the browser

const DEBOUNCE_MS = 250;   // 200–300ms. Not zero.
const MIN_CHARS = 3;       // "1" matches nothing useful

let timer = null;
let inFlight = null;

/**
 * Debounced, cancellable address autocomplete.
 *
 * Two things prevent the bill:
 *   1. Debounce — one request per pause, not per keystroke
 *   2. AbortController — cancel the previous request when a newer one starts
 */
export function autocompleteAddress(query, { at, countryCode, limit = 5 }) {
  return new Promise((resolve, reject) => {
    clearTimeout(timer);

    if (query.length < MIN_CHARS) {
      resolve([]);
      return;
    }

    timer = setTimeout(async () => {
      // Cancel the previous in-flight request. The user has typed more;
      // its result is already stale.
      inFlight?.abort();
      const ctrl = new AbortController();
      inFlight = ctrl;

      const params = new URLSearchParams({
        q: query,
        limit: String(limit),
        apiKey: API_KEY,
      });
      // Bias toward the user's location. Improves relevance materially.
      if (at) params.set("at", at);                     // "lat,lng"
      if (countryCode) params.set("in", `countryCode:${countryCode}`);

      const timeout = setTimeout(() => ctrl.abort(), 5_000);

      try {
        const resp = await fetch(`${HOST}?${params}`, { signal: ctrl.signal });
        if (resp.status === 403) throw new Error("Autocomplete not entitled");
        if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);

        const { items = [] } = await resp.json();
        resolve(items.map((it) => ({
          label: it.address.label,
          hereId: it.id,          // ← store this. Resolve later with /lookup.
          resultType: it.resultType,
          highlights: it.highlights,   // for bolding the matched substring
        })));
      } catch (err) {
        if (err.name === "AbortError") return;   // superseded. Not an error.
        reject(err);
      } finally {
        clearTimeout(timeout);
      }
    }, DEBOUNCE_MS);
  });
}

import os
import requests

HOST = "https://autocomplete.search.hereapi.com/v1/autocomplete"
API_KEY = os.environ["HERE_API_KEY"]


class EntitlementError(Exception): ...


def autocomplete(query: str, at: str | None = None,
                 country: str | None = None, limit: int = 5) -> list[dict]:
    """
    Server-side autocomplete — e.g. behind your own debounced proxy.

    Debouncing belongs in the CLIENT. If you call this per keystroke
    from a backend, you have moved the problem, not solved it.
    """
    if len(query) < 3:
        return []

    params = {"q": query, "limit": limit, "apiKey": API_KEY}
    if at:
        params["at"] = at                       # "lat,lng" — biases relevance
    if country:
        params["in"] = f"countryCode:{country}"  # ISO 3166-1 alpha-3

    resp = requests.get(HOST, params=params, timeout=5)
    if resp.status_code == 403:
        raise EntitlementError("Autocomplete not entitled")
    resp.raise_for_status()

    return [
        {
            "label": it["address"]["label"],
            "here_id": it["id"],
            "result_type": it["resultType"],
        }
        for it in resp.json().get("items", [])
    ]

# Address completion — checkout, delivery, dispatch
curl -G 'https://autocomplete.search.hereapi.com/v1/autocomplete' \
  --data-urlencode 'q=425 W Randolph' \
  --data-urlencode 'at=41.8845,-87.6386' \
  --data-urlencode 'in=countryCode:USA' \
  --data-urlencode 'limit=5' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Autosuggest — places, categories, misspellings. A DIFFERENT endpoint.
curl -G 'https://autosuggest.search.hereapi.com/v1/autosuggest' \
  --data-urlencode 'q=resta' \
  --data-urlencode 'at=52.5200,13.4050' \
  --data-urlencode 'limit=5' \
  --data-urlencode "apiKey=${HERE_API_KEY}"