/autocomplete

Type-ahead geocoding — returns results as the user types.

GET https://api.geoheim.com/autocomplete

Parameters

Parameter	Type	Description
`q`required	string	Partial query string. Send as the user types — results improve with each keystroke.`"Stock" / "Stockho" / "Stockholm"`
`format`	stringdefault: "json"	Response format.`"json" \| "geojson"`
`countrycodes`	string	Restrict to countries (ISO 3166-1 alpha-2).`"se" / "de,at,ch"`
`limit`	integerdefault: 5	Max results. Keep low (5-10) for autocomplete UX.`5`
`viewbox`	string	Bias results toward this bounding box.`"17.9,59.8,18.2,59.9"`
`key`	string	API key as query parameter (header preferred).

Example

curl "https://api.geoheim.com/autocomplete?q=Stockho&format=json&limit=5" \
  -H "Authorization: Bearer hk_live_…"

Best practices

1.Debounce requests. Wait 150-300ms after the last keystroke before sending. Saves your quota and reduces flickering.
2.Start at 3+ characters. Single-character queries return too many results. Wait until the user has typed at least 3 characters.
3.Use viewbox for location bias. If you know the user's approximate location, pass it as a viewbox to get more relevant suggestions.
4.Cancel in-flight requests. Use AbortController to cancel the previous request when a new keystroke arrives.

JavaScript example

autocomplete.js

let controller = null;

async function autocomplete(query) {
  // Cancel previous request
  if (controller) controller.abort();
  controller = new AbortController();

  const res = await fetch(
    `https://api.geoheim.com/autocomplete?q=${encodeURIComponent(query)}&limit=5`,
    {
      headers: { "Authorization": "Bearer hk_live_…" },
      signal: controller.signal,
    }
  );
  return res.json();
}

// Debounce: call autocomplete 200ms after last keystroke
let timer;
input.addEventListener("input", (e) => {
  clearTimeout(timer);
  if (e.target.value.length < 3) return;
  timer = setTimeout(() => autocomplete(e.target.value), 200);
});

/autocomplete vs /search

/autocomplete is optimized for partial queries and speed — it uses prefix matching and skips some of the heavier ranking logic. Use it for type-ahead UI. Use /search for final, complete queries where accuracy matters most.