Forward-geocode a place name or US ZIP.
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.
Request
- Base URL: https://api.smarterweather.com
- URL: https://api.smarterweather.com/v1/geocode/search
- Auth: HTTP bearer
Query parameters
City name to resolve. Mutually exclusive with zipcode. Permits the same character set as autosuggest.input.
Optional 2-letter US state code or full state name to disambiguate the city query. Ignored when zipcode is set.
5-digit US ZIP code. Mutually exclusive with city.
Response
Match results. Empty results array when no candidates match the query.
Example response
{
"results": [
{
"name": "Chicago",
"state": "IL",
"state_name": "Illinois",
"county": "Cook",
"zip": "60601",
"lat": 41.8781,
"lon": -87.6298,
"population": 2746388,
"timezone": "America/Chicago",
"type": "place",
"place_id": "1714000",
"id": "addr:123-main-st-naperville-il",
"title": "123 Main St",
"subtitle": "Naperville, IL 60540"
}
],
"meta": {
"schema_version": "1.0.0",
"freshness": [
{
"source": "rtma",
"product_id": "rtma_conus_2p5km"
}
],
"warnings": [
{
"code": "partial_fetch",
"section": "alerts",
"product_id": "airquality_combined",
"fields": [
"aqi",
"aqi_category",
"pm25",
"ozone",
"pm10"
]
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.