---
title: "Forward-geocode a place name or US ZIP."
method: GET
path: "/v1/geocode/search"
tags: ["Geocode"]
---

# Forward-geocode a place name or US ZIP.

`GET /v1/geocode/search`

## Request

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

Returns location candidates matching either a 5-digit US `zipcode`
or a `city` (with optional `state` disambiguator). Exactly one
of `city` or `zipcode` must be supplied.

### Caching

Successful responses carry `Cache-Control: private,
max-age=3600`. The underlying place-name <-> ZIP mapping is
stable on the order of months.

`private` lets your own client reuse the response for the full
`max-age` while keeping shared caches (CDNs, proxies) out, since
each request on a partner key is metered and rate-limited
individually.

### Auth

Standard sw-api Bearer auth applies.

## Query parameters

- `city` string
- `state` string
- `zipcode` string

## Response `200`

Match results. Empty `results` array when no candidates
match the query.

- 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.
- `404`: Resource not found: a location that cannot be resolved (unknown ZIP, unrecognised free-text location), no upstream data for the location, or a missing resource. On a route that checks coverage (its description says so), a location outside the 50 US states and DC returns type `https://smarterweather.com/errors/outside-coverage`; that and the location-not-found problem carry `next_steps` (`recommended = coverage`).
- `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)