---
title: "Typeahead-style location lookup."
method: GET
path: "/v1/geocode/autosuggest"
tags: ["Geocode"]
---

# Typeahead-style location lookup.

`GET /v1/geocode/autosuggest`

## Request

- Base URL: `https://api.smarterweather.com`
- URL: `https://api.smarterweather.com/v1/geocode/autosuggest`
- Auth: HTTP bearer

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.

## Query parameters

- `input` string, required
- `count` integer
- `include` string
- `bias_lat` number, double
- `bias_lon` number, double

## Response `200`

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.

- GeocodeResultsResponse: Envelope returned by `GET /v1/geocode/autosuggest` and `GET /v1/geocode/search`. `results` is always present. `meta` is a stable, documented, optional field: autosuggest includes it only when the results are incomplete, and clients should treat any `meta.warnings` entry as incomplete results. Additional undocumented sibling fields may appear without a sw-api release (e.g. server-side annotations); ignore them. An empty array is returned when no candidates match.
  - `results` GeocodeAutosuggestResult[], required: Match candidates, ordered by match score (best first).
    - `name` string, nullable: Populated-place name.
    - `state` string, nullable: 2-letter US state code.
    - `state_name` string, nullable: Full state / region label.
    - `county` string, nullable: County or equivalent admin-2 area.
    - `zip` string, nullable: Representative ZIP for the place (or query ZIP for ZIP search).
    - `lat` number, double, nullable: Centroid latitude in decimal degrees.
    - `lon` number, double, nullable: Centroid longitude in decimal degrees.
    - `population` integer, nullable: Population estimate, when known.
    - `timezone` string, nullable: IANA timezone identifier covering the centroid.
    - `type` string: Result kind. Emitted values are `place`, `zip`, `address`, `poi`. Treat as opaque -- new types may appear without a sw-api release.
    - `place_id` string, nullable: Census place GEOID. Same key as the v2 basemap tile `id`. Present on place results; omitted for ZIP results.
    - `id` string: Stable row id for address and POI hits (and some place rows). Omitted when the result has no id.
    - `title` string: Primary two-line copy (street or POI name). Prefer over `name` for `address` and `poi` rows.
    - `subtitle` string: Secondary two-line copy (city, state, ZIP).
  - `meta` Meta: Per-response metadata: response schema version, generation time, upstream data freshness, and any non-fatal warnings.
    - `schema_version` string, required: Response schema version, a semver string (currently `1.0.0`). The major part changes only with a non-additive change, which follows the deprecation policy. Cache on it if you cache response shapes.
    - `generated_at` string, date-time, required: Server time at which this response body was generated.
    - `freshness` SourceFreshness[]: Freshness metadata for each upstream data source used.
      - `source` string, required: Source family (e.g., `rtma`, `hrrr`, `nbm`, `mrms`).
      - `product_id` string, required: Specific product identifier.
      - `reference_time` string, date-time, nullable: Model run / observation reference time.
      - `latest_valid` string, date-time, nullable: Latest valid time represented in the source.
      - `age_seconds` integer, required: Seconds elapsed since `reference_time`.
    - `warnings` MetaWarning[]: Non-fatal warnings generated during request fulfillment. Each entry has a stable `code` clients can branch on and a human-readable `detail`.
      - `code` 'partial_fetch' | 'upstream_timeout' | 'upstream_unavailable' | 'coverage_limited' | 'geocode_ambiguous' | 'stale_response' | 'stale_source' | 'not_enabled', required: Stable machine-parseable warning code. Clients should branch on `code`, not on `detail`. - `partial_fetch`: the section could not be fully fetched and is missing or incomplete. - `upstream_timeout`: an upstream weather source timed out, so the section is missing or incomplete. - `upstream_unavailable`: an upstream weather source was unreachable, so the section is missing or incomplete. - `coverage_limited`: the data does not cover this location (for example no nearby station, or a product outside its domain); retrying will not help. - `geocode_ambiguous`: the place name matched more than one location; the response uses the best match. - `stale_response`: the section was served from a recent cached copy because the upstream source failed. - `stale_source`: one upstream product's latest data is older than its source's freshness limit. `product_id` names the product (its age is the `meta.freshness` entry with the same `product_id`) and `fields` lists the fields in `section` it leaves `null` (or omits, for optional fields such as `aqi_category`). Unlike `stale_response`, the response was not replayed from cache. - `not_enabled`: the requested section is not enabled for this API key. New codes may be added without a breaking-change announcement; treat an unknown code as informational.
      - `section` string, required: Response section the warning applies to (e.g., `"alerts"`, `"hourly"`, `"outlooks"`). May also be `"_request"` for request-level warnings.
      - `detail` string: Human-readable explanation.
      - `product_id` string: Catalog product id (`GET /v1/catalog/{product_id}`) of the upstream product the warning is about; the same id as the product's `meta.freshness` entry. Set only for `stale_source`.
      - `fields` string[]: Response fields in `section` that this warning leaves `null` or omits. Set only for `stale_source`.
    - `hourly_sampling` object: Present only when `hourly_step` dropped at least one hourly row. Echoes the effective thinning so a thinned series is distinguishable from a short forecast: every row is kept below `from_hour` hours from `hourly[0].time`, then one row every `step_hours` hours.
      - `step_hours` integer, required: Effective `hourly_step`.
      - `from_hour` integer, required: Effective `hourly_step_from`.

## Other responses

- `400`: Bad request.
- `401`: Missing or invalid API key. Carries a `WWW-Authenticate` challenge and a `next_steps` extension. `recommended` is `device_flow`: the object is a complete no-install mint recipe.
- `402`: Trial key free value ended (lifetime cap spent or key clock expired) while the claim window is still open. Carries `next_steps.recommended = claim` and the per-key claim href.
- `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension.
- `429`: Rate limit exceeded. Carries a `next_steps` extension (`recommended: upgrade`, plus `pricing` and `usage`) telling the caller how to lift the limit.
- `500`: Internal server error.
- `502`: Bad gateway. The service received an invalid response from an upstream data source. Transient; clients should retry with backoff.
- `503`: Service unavailable. An upstream dependency is unavailable or shedding load (type `service-unavailable`). Transient; retry with backoff and honor any `Retry-After` header.
- `504`: Gateway timeout. An upstream data source did not respond within the service's budget.

---

[API](https://skmtc.dev/smarterweather/apis/smarter-weather-api.md) · [All operations](https://skmtc.dev/smarterweather/apis/smarter-weather-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smarterweather/apis/smarter-weather-api/revisions/520d55a696e4?raw)