Docs navigation
Reference
Agents
Turn a ZIP code into coordinates
Send a 5-digit ZIP to /v1/geocode/search and you get the place, its county and time zone, and one latitude and longitude for it.
The request
GET/v1/geocode/search
| Parameter | Value | What it does |
|---|---|---|
zipcode | 80202 | 5-digit US ZIP code. |
Call it
# first, read the key from .env (never source it as shell):
export SMARTERWEATHER_API_KEY="$(sed -n 's/^\(export \)\{0,1\}SMARTERWEATHER_API_KEY=//p' .env | tail -n 1 | tr -d "\r\"' ")"
curl "https://api.smarterweather.com/v1/geocode/search?zipcode=80202" \
-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?zipcode=80202",
{ 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));# pip install requests python-dotenv
import os, sys, requests
from dotenv import load_dotenv
load_dotenv(".env") # ./.env in the current directory; variables already set are kept
r = requests.get(
"https://api.smarterweather.com/v1/geocode/search?zipcode=80202",
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?zipcode=80202", 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))
}{
"name": "search_locations",
"arguments": {
"query": "80202"
}
}Your agent can ask the same question through the hosted weather MCP (36 tools).
Run this toolOne-click installs are global; for the key, put the per-project config in the project's .cursor/mcp.json / .vscode/mcp.json.
The key is read from SMARTERWEATHER_API_KEY, the same as on every docs page and in the playground. The code is identical to the playground's “Call it yourself”.
What it answers
Example answer from the recorded sample, Oct 15, 2026 · ZIP 80202
80202 is Denver County, Colorado, at 39.7515, -104.9977 (America/Denver).
- Latitude39.7515
results[0]. lat - Longitude-104.9977
results[0]. lon - Time zoneAmerica/Denver
results[0]. timezone
Fields it reads:
results[].latresults[].lonresults[].countyresults[].state_nameresults[].timezone
Gotchas
- Send zipcode or city, not both. state only narrows a city search.
- The coordinates are one point for the whole ZIP, not a street address.
- /v1/weather takes zip directly. Geocode first only when you need the place or want to store the point.