The response carries the next request
Coordinates and codes from a postal lookup can go straight into related lookups, without translating them first.
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.
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.