---
title: "Reverse-geocode a coordinate to a location."
method: GET
path: "/v1/geocode/reverse"
tags: ["Geocode"]
---

# Reverse-geocode a coordinate to a location.

`GET /v1/geocode/reverse`

## Request

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

Resolves a `(lat, lon)` coordinate into a city / nearest-city /
state / county / IANA timezone tuple. Coverage is the 50 US
states and DC; other points return 404 `outside-coverage` with
`next_steps`.

### Caching

Successful responses carry `Cache-Control: private,
max-age=86400`. The underlying place-name <-> timezone mapping
changes on the order of years; clients should treat this as a
long-term cache. The exception is a temporarily degraded or
fallback answer, which is sent with `Cache-Control: no-store` so
that no cache keeps it.

`private` means your own client may store the response for the
full `max-age`, but shared caches (CDNs, proxies) must not:
every request on a partner key is metered and rate-limited
individually, so it has to reach the origin. The freshness
budget is unchanged either way.

### Auth

Standard sw-api Bearer auth applies.

## Query parameters

- `lat` number, double, required
- `lon` number, double, required

## Response `200`

Resolved location metadata.

- ReverseGeocodeResponse: Resolved place metadata for a `(lat, lon)` query against `GET /v1/geocode/reverse`. All fields are best-effort: `city` is populated when the coordinate falls inside a populated-place polygon; `nearest_city` is populated when the coordinate is outside any city polygon but within the resolution radius of one. `state` carries the canonical NWS region label. Forward-compat: additional fields may appear in this object without a sw-api release.
  - `city` string: Populated-place name when the query coordinate falls inside a city polygon. Empty when only `nearest_city` is set.
  - `nearest_city` string: Closest populated-place name when the query coordinate is outside any city polygon. Empty when `city` is set.
  - `state` string: Canonical NWS state / region label (e.g. "Illinois", "Puerto Rico").
  - `county` string: County or equivalent admin-2 area, when available.
  - `timezone` string: IANA timezone identifier covering the query coordinate.

## 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)