Geocoding

Autocomplete — search-as-you-type place suggestions

Purpose-built typeahead: partial input → ranked place suggestions at per-keystroke latency. Edge-cached on normalized prefix (24h) — repeat prefixes are served sub-50ms with X-Cache: HIT. Pass focus_lat/focus_lon for proximity-biased, distance-guarded results, or boundary_country/bounds for hard filters. Free tier. For full geocoding (addresses, intersections, confidence ladder) use /v1/geocode.

get/v1/autocomplete

Request

  • Base URL: https://geo.thinair.co
  • URL: https://geo.thinair.co/v1/autocomplete
  • Auth: HTTP bearer

Query parameters

textstring required

Partial input under the user's cursor. Fires from 2 characters when the request is scoped (focus/bounds/country), or 3 characters for a global query; shorter inputs return an empty result with a min_length warning (HTTP 200 — no engine call, so a bare 1-char never hits the engine).

focus_latnumber nullable

Latitude of the proximity bias point. When set (with focus_lon), results are biased toward it AND results farther than ~500 km are dropped unless nothing is within range.

Example:47.6062
focus_lonnumber nullable

Longitude of the proximity bias point.

Example:-122.3321
boundary_countrystring

ISO 3166-1 alpha-2 or alpha-3 country code — hard filter.

Example:US
boundsstring

Bounding-box hard filter as minLon,minLat,maxLon,maxLat (WGS84 degrees).

Example:-123.1,47.0,-121.9,48.0
layersstring

Comma-separated layer filter: venue, street, address, intersection, locality, neighbourhood, borough, county, localadmin, region, country, postalcode, coarse. Unknown layers are ignored.

Example:locality,venue
sizeinteger

Maximum suggestions to return (1–10). Default 5.

Example:5
langstring

Preferred label language (ISO 639-1 / BCP47), passed through to the engine.

Example:en

Response

Ranked suggestion list. X-Cache: HIT|MISS reports edge-cache status.

warningsstring[]

Soft signals: min_length (input below the engine floor — 3 chars global, 2 chars when scoped by focus/bounds/country; engine skipped), focus_distance_filtered (far results dropped), no_results_near_focus (nothing within ~500 km of focus; honest unfiltered set returned), country_filtered (a result outside boundary_country was dropped by the hard-filter backstop), bounds_filtered (a result outside bounds was dropped by the rect backstop), no_focus_ambiguous (no focus/bounds/country given and the top result's country differs from the caller's geo-IP country), short_final_token_dropped (a 1-char final token was stripped from the engine query; the full text is still echoed in meta.query), negative_cached (served from the short-TTL timeout/empty negative cache), upstream_degraded (that negative entry recorded a recent engine timeout), autocomplete_more_context_required (2-char input without focus/bounds/country — add one to enable suggestions at this length), autocomplete_cache_only (1-char input — served from the prefilled cache only, never the engine), autocomplete_timeout (engine exceeded the per-call ceiling; degraded to an empty 200).

Example response

{
  "items": [
    {
      "id": "ta_place_8f3a2c9e61c04d58"
    }
  ],
  "meta": {
    "cacheHitKind": "v3_hit",
    "source": "engine",
    "cacheTier": "edge"
  },
  "warnings": [
    "no_focus_ambiguous"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.