Autocomplete

Autocomplete delivers low-latency suggestions optimised for prefix searches. It shares the same filters as forward search while adjusting ranking to favour short, partial text.

OpenAPI links

See GET /autocomplete for request contracts, validation rules, and error models.

Try it: GET /autocomplete

Query parameters

Name	Required	Description
text	Yes	Partial query term (1–512 characters). Empty strings return HTTP 400.
size	No	Maximum number of suggestions to return (1–40, default 10). Smaller sizes improve latency.
focus.point.lat, focus.point.lon	No	Bias suggestions toward a user’s current location.
boundary.circle.*, boundary.rect.*	No	Restrict matches to a circular or rectangular area. Circles default to a 50 km radius.
boundary.country, boundary.gid	No	Limit results to named geographies.
sources, layers	No	Filter datasets or feature types (for example layers=address,street).

Keeping suggestions relevant

• Bias results with focus.point.* or boundary.circle.* so that the first matches are local to the user.
• Restrict layers to address or venue when building address entry flows; include locality for city pickers.
• Trim size to the number of results you actually display to keep payloads and latency low.
• Reuse the same API key and caching strategy as forward search; responses share the GeoJSON envelope.

Sample request

cURL

curl -s -G 'https://api-na.geobridge.io/v1/autocomplete' \
  -H 'Accept: application/json' \
  -H "X-API-Key: ${GEOBRIDGE_API_KEY}" \
  --data-urlencode 'text=hard rock' \
  --data-urlencode 'focus.point.lat=52.5' \
  --data-urlencode 'focus.point.lon=13.3' \
  --data-urlencode 'size=5'

Node.js

const apiKey = process.env.GEOBRIDGE_API_KEY;
const params = new URLSearchParams({
  text: 'hard rock',
  'focus.point.lat': '52.5',
  'focus.point.lon': '13.3',
  size: '5',
});
const url = `https://api-na.geobridge.io/v1/autocomplete?${params.toString()}`;

const response = await fetch(url, {
  headers: {
    Accept: 'application/json',
    'X-API-Key': apiKey,
  },
  signal: AbortSignal.timeout(5000),
});

if (!response.ok) {
  throw new Error(`Autocomplete failed: ${response.status} ${response.statusText}`);
}

const payload = await response.json();
console.log(payload.features.map((f) => f.properties.label));

Python

import os
import requests

api_key = os.environ["GEOBRIDGE_API_KEY"]

resp = requests.get(
    "https://api-na.geobridge.io/v1/autocomplete",
    headers={
        "Accept": "application/json",
        "X-API-Key": api_key,
    },
    params={
        "text": "hard rock",
        "focus.point.lat": 52.5,
        "focus.point.lon": 13.3,
        "size": 5,
    },
    timeout=5,
)
resp.raise_for_status()

print([f["properties"]["label"] for f in resp.json().get("features", [])])

Handling errors and retries

• Autocomplete rejects missing text parameters with HTTP 400. Pre-validate input and fall back to client-side suggestions if needed.
• A slow upstream shard may yield HTTP 408 or HTTP 504. Retry quickly or fail open to keep typing responsive.
• Transient HTTP 5xx responses are safe to retry with short backoff windows.