Blog·Craft·

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.