Geocode

Reverse-geocode a coordinate to a location.

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.

get/v1/geocode/reverse

Request

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

Query parameters

latnumber double required

Latitude in decimal degrees, range [-90, 90].

lonnumber double required

Longitude in decimal degrees, range [-180, 180].

Response

Resolved location metadata.

citystring

Populated-place name when the query coordinate falls inside a city polygon. Empty when only nearest_city is set.

nearest_citystring

Closest populated-place name when the query coordinate is outside any city polygon. Empty when city is set.

statestring

Canonical NWS state / region label (e.g. "Illinois", "Puerto Rico").

countystring

County or equivalent admin-2 area, when available.

timezonestring

IANA timezone identifier covering the query coordinate.

Example response

{
  "city": "Chicago",
  "nearest_city": "Naperville",
  "state": "Illinois",
  "county": "Cook",
  "timezone": "America/Chicago"
}

Changes

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