A ZIP code can be the starting point for more than a city and state. If you're building a local weather page, for example, you need coordinates next. I want the postal response to give you values you can actually use in that next call.
Here is part of the response for Denver's 80202:
GET /postal/80202?country=US
{
"postal": "80202",
"city": "Denver",
"state": "CO",
"country": "US",
"latitude": 39.751526,
"longitude": -104.997673,
"timezone": "America/Denver"
}
Take latitude and longitude and send them as lat and lon to /weather:
GET /weather?lat=39.751526&lon=-104.997673
The same coordinates work on /point, /elevation, and /time. You don't need to geocode the city name in between. They represent the postal area, though, so they aren't a substitute for the coordinates of a specific street address.
Check that both coordinates are present before building that second request. This helper returns a request path when the postal result has a usable pair, and null when it doesn't:
function weatherPath(place) {
if (!Number.isFinite(place.latitude) || !Number.isFinite(place.longitude)) {
return null
}
const query = new URLSearchParams({
lat: String(place.latitude),
lon: String(place.longitude)
})
return `/weather?${query}`
}
Zero is a valid latitude or longitude, so checking if (place.latitude) would discard some real coordinates. Missing values need their own branch: show that weather is unavailable or ask for a more precise location, rather than sending guessed coordinates.
The codes connect in the same way. CO and US give you /state/CO?country=US. US works on /country/US; its currency code, USD, works on /currency/USD. If you want to explore nearby postal codes, request postal detail with ?deep=true on a paid plan. Its deep.neighbors list supplies those inputs.
This is how I want the endpoints to fit together: get the answer you came for, then use the fields you already have when you need to ask something else.