Typeahead-style location lookup.
Returns up to count location candidates whose names match the partial input string. Designed for client-side typeahead widgets: lookups use a prefix index, so latency stays low as you type.
Caching
A complete response carries Cache-Control: max-age=30, so repeated keystrokes for the same text reuse it for 30 seconds. Partner keys get private, max-age=30: your own client may reuse the response for the full max-age, while shared caches (CDNs, proxies) stay out, since each request on a partner key is metered and rate-limited individually. First-party callers get public, max-age=30.
A response with incomplete results (an upstream_timeout or partial_fetch warning; see the 200 response) is sent with Cache-Control: no-store, so no cache replays a partial list after the upstream recovers. A not_enabled warning alone keeps the headers above, except while the server cannot confirm your key's access, when it is also no-store.
Auth
Standard sw-api Bearer auth applies.
Request
- Base URL: https://api.smarterweather.com
- URL: https://api.smarterweather.com/v1/geocode/autosuggest
- Auth: HTTP bearer
Query parameters
Partial place-name to expand. 2-128 characters, restricted to alphanumerics + spaces + ,, ., -, ', #, and /.
Maximum number of results (1-100). Defaults to 10.
Experimental (x-stability: experimental): excluded from the 90-day breaking-change commitment.
Comma-separated extra result classes to mix into the typeahead. Allowlisted tokens: address, poi. Omitted or empty keeps the legacy place+ZIP-only response.
Address and POI results are not yet available to every API key. When they are not enabled for your key, the request still succeeds with place and ZIP results only, and meta.warnings[] carries one not_enabled warning per requested section (section is address or poi), so you can tell "not enabled" from "no match". not_enabled is a stable state of your key, not an incomplete result: do not retry. Unknown tokens still return 400.
Soft rank bias latitude. Must be paired with bias_lon. Range [-90, 90]. The bias is applied at 0.1° precision.
Soft rank bias longitude. Must be paired with bias_lat. Range [-180, 180]. The bias is applied at 0.1° precision.
Response
Match results. Empty results array when no candidates match the input.
A result section that did not finish still returns 200 with whatever rows are available, and is reported in meta.warnings[]: code is upstream_timeout or partial_fetch, and section is address, poi, or _request (one warning covering any other incomplete part of the request, such as an unreadable upstream status). detail is human-readable text; branch on code and section, not detail. Treat an upstream_timeout or partial_fetch warning as incomplete results; such a response is sent with Cache-Control: no-store.
not_enabled (section address or poi) is different: the section was requested through include but is not enabled for your key. It is a stable state, not an incomplete result. Do not retry. See Caching above for its Cache-Control.
meta is absent when there is nothing to report.
Example response
{
"results": [
{
"name": "Chicago",
"state": "IL",
"state_name": "Illinois",
"county": "Cook",
"zip": "60601",
"lat": 41.8781,
"lon": -87.6298,
"population": 2746388,
"timezone": "America/Chicago",
"type": "place",
"place_id": "1714000",
"id": "addr:123-main-st-naperville-il",
"title": "123 Main St",
"subtitle": "Naperville, IL 60540"
}
],
"meta": {
"schema_version": "1.0.0",
"freshness": [
{
"source": "rtma",
"product_id": "rtma_conus_2p5km"
}
],
"warnings": [
{
"code": "partial_fetch",
"section": "alerts",
"product_id": "airquality_combined",
"fields": [
"aqi",
"aqi_category",
"pm25",
"ozone",
"pm10"
]
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.