Skip to content
Docs navigation

Agents as developers

Geocoding

Smarter Weather covers the 50 US states and DC only. Every route that takes a point (lat and lon, zip or location) returns 404 outside-coverage for a point outside the 50 states and DC. /v1/alerts and /v1/observations return it for a bounding box that touches no US domain (CONUS, Alaska, Hawaii); a box that touches one may still include area outside the US. /v1/weather/batch reports it per item as outside_coverage, and /v1/point with points and /v1/series/batch mark such points out_of_domain, as they do a point the check could not reach in time (retry it). If the location lookup is unavailable, the check can briefly fail open. Routes keyed by a station, radar site, forecast office or alert id, and nationwide lists, are not filtered by point, so do not treat an empty result as an all-clear. See Errors.

Convert between coordinates and place names across the supported NWS domain. Use reverse geocoding to resolve coordinates, forward search to look up cities and ZIP codes, and autosuggest for real-time search interfaces.

Operations

Reverse geocode

Convert latitude/longitude coordinates to a place name (city, state, county, timezone). Useful for resolving GPS readings before a weather request.

Autosuggest

Location autocomplete from partial user input. Returns ranked suggestions for search bars and location pickers.

Forward search

Look up coordinates by city/state or US ZIP code. Returns the canonical location plus metadata.

When to use which

  • Building a location picker? Use autosuggest as the user types and forward search when they pick a result or paste a ZIP code.
  • Have device coordinates? Run them through reverse geocode to get a human-readable label before calling the weather endpoint.
  • Bulk-importing addresses? Use forward search for the city/state or ZIP-keyed paths and fall back to autosuggest for ambiguous strings.
# first: export SMARTERWEATHER_API_KEY=sw_live_... (or: set -a; source .env; set +a)
curl "https://api.smarterweather.com/v1/geocode/search?city=Boston&state=MA" \
  -H "Authorization: Bearer $SMARTERWEATHER_API_KEY"
// save as sample.mjs; run: node --env-file=.env sample.mjs (Node 20.6+, ESM top-level await)
const res = await fetch(
  "https://api.smarterweather.com/v1/geocode/search?city=Boston&state=MA",
  { headers: { Authorization: `Bearer ${process.env.SMARTERWEATHER_API_KEY}` } },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(JSON.stringify(data, null, 2));
import os, sys, requests

r = requests.get(
    "https://api.smarterweather.com/v1/geocode/search",
    params={"city":"Boston","state":"MA"},
    headers={"Authorization": f"Bearer {os.environ['SMARTERWEATHER_API_KEY']}"},
)
if not r.ok:
    sys.exit(f"{r.status_code} {r.text}")
data = r.json()
print(data)
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.smarterweather.com/v1/geocode/search?city=Boston&state=MA", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SMARTERWEATHER_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)
	if err != nil {
		log.Fatal(err)
	}
	if res.StatusCode < 200 || res.StatusCode > 299 {
		log.Fatalf("%s %s", res.Status, body)
	}
	fmt.Println(string(body))
}

Geocoding reference

Rendered live from the canonical OpenAPI document. This is the canonical reference for the geocoding resource.

Paste a test key (sw_test_*) from your dashboard into Test Request. Calls with your own key count toward your plan.

Loading API reference…