Recipe: Postal code → place lookup

The task

You have a ZIP or postal code and need the city/state/coordinates it resolves to — no more, no less, one call.

Tool used: lookup_zipcode. Fallback for unsupported countries: get_weather (Open-Meteo geocoder via the weather pack). See Caveats for the reverse direction (city → postal code), which does not currently work — don’t build a recipe prompt around it.

Copy-paste prompt

Resolve this postal code to a place using Pipeworx's lookup_zipcode tool: city, state/region,
and coordinates. Country is <ISO 3166-1 alpha-2 code, e.g. "us">, code is "<postal code>".
If it's not found, tell me plainly rather than guessing a nearby city.

What a good answer looks like

lookup_zipcode({ country: "us", zipcode: "90210" })

returns (live call, 2026-08-06):

{
  "post_code": "90210",
  "country": "United States",
  "country_abbreviation": "US",
  "found": true,
  "places": [
    { "name": "Beverly Hills", "state": "California", "state_abbreviation": "CA", "lat": 34.0901, "lon": -118.4065 }
  ]
}

A trustworthy answer has:

  • found: true plus a non-empty places array — found is the field to check, not just the presence of a response object (see the failure mode below).
  • places as an array, not a single object. US ZIPs can map to multiple cities at boundary codes — don’t assume places[0] is the only or canonical answer; say how many there are if more than one.
  • lat/lon as numbers, ready to chain into weather, attom, or any other geo-aware tool without re-parsing strings.

A plausible-sounding failure looks like a clean, well-formed {found: false} object — not a crash, not an error. That’s correct behavior for a genuinely bad code:

lookup_zipcode({ country: "ke", zipcode: "00100" })  // Kenya — outside Zippopotam's coverage
// → { country: "ke", zipcode: "00100", found: false,
//     hint: "Postal code not found. Zippopotam coverage varies by country (best for US, GB, DE, FR, CA, AU, NL, JP)." }

The trap is reading found: false as “that code doesn’t exist” when it may just mean “outside this tool’s ~60-country coverage.” Check the hint before concluding anything about the code itself, and route to the fallback (below) rather than reporting the code as invalid.

Step-by-step tool calls

US ZIP

lookup_zipcode({ country: "us", zipcode: "90210" })
// → Beverly Hills, CA — see full response above

UK postcode

lookup_zipcode({ country: "gb", zipcode: "SW1A 1AA" })
// → resolves to Westminster

Country outside Zippopotam’s coverage

// Skip zippopotam entirely once you know the country is unsupported.
get_weather({ location: "Nairobi, Kenya" })
// → { location: "Nairobi", country: "Kenya", latitude: -1.28333, longitude: 36.81667,
//     temperature_f: 64.4, conditions: "Overcast", ... }

Don’t fold the postal code itself into the geocoder query string. Live-verified: get_weather({ location: "00100, Nairobi, Kenya" }) fails to resolve at all —

{ "error": "tool_error", "message": "Could not resolve location \"00100, Nairobi, Kenya\" via Open-Meteo geocoding..." }

— while the identical query without the postal-code prefix, "Nairobi, Kenya", resolves cleanly. Open-Meteo’s geocoder matches place names, not postal codes; it doesn’t ignore the extra token, it fails the whole match. Drop the code and geocode on city + country only.

Pattern: validated lookup with fallback

async function resolvePostalCode(country, zipcode, cityHint) {
  const result = await lookup_zipcode({ country, zipcode })
  if (result.found) return result.places[0]

  // Fallback: geocode by city name only — never pass the postal code itself
  if (cityHint) {
    const fallback = await get_weather({ location: cityHint })
    if (fallback.latitude) {
      return { name: fallback.location ?? cityHint, lat: fallback.latitude, lon: fallback.longitude }
    }
  }
  return null
}

Citation pattern

90210 resolves to Beverly Hills, CA (34.09°N, 118.41°W) per Zippopotam.

Caveats

  • The reverse direction — city → postal code(s) — does not currently work. lookup_city is wired to https://api.zippopotam.us/<country>/<state>/<city>, but Zippopotam’s public API has no such endpoint; live-verified 2026-08-06 that this path 404s for every input tried, including well-known cities, confirmed with a direct curl against the upstream (not just our wrapper). It returns a clean {found: false} rather than crashing, so it fails quietly instead of loudly — don’t reach for it, and don’t trust a found: false from it as meaning the city doesn’t exist. Filed as a fix/deprecation task 2026-08-06 (fleet #135); there is no working substitute for city → postal-code in the current catalog.
  • Country code is ISO-3166-1 alpha-2, lowercase. "us" not "USA", "gb" not "UK".
  • Postal code formats vary by country. US is 5 digits or 5+4. UK is alphanumeric with a space ("SW1A 1AA"). Check the format before assuming a fixed pattern applies everywhere.
  • Multiple places per code. US ZIPs can map to multiple cities. Returns are an array — don’t assume .places[0] is canonical without checking the length.
  • ~60-country coverage, best for US/GB/DE/FR/CA/AU/NL/JP/MX/BR/ES/IT/BE. For anything else, route straight to the weather pack’s geocoder (city + country string, no postal code) — see Step-by-step above.

Last reviewed August 6, 2026