Skip to content

ZIP codes

What a ZIP code (a Census ZCTA) covers — its state, a point inside it, the NWS zones it overlaps and their SAME codes — is on client.zips. It needs the read:observations scope; without it a lookup raises ZipLookupForbiddenError.

from stormlore import Client

client = Client()
lookup = client.zips.lookup(["68102", "02134"])
lookup["68102"].zones          # NWS zones, each with ugc, type and name
lookup.unknown                 # codes the reference data has no ZCTA for
lookup.to_dataframe()          # zip, state, lat, lon, zones (UGC codes), same

Each code must be five digits (else ValueError, before any request); repeats are dropped. More than 200 codes are sent 200 at a time and merged into one result, sorted by ZIP. An unknown code is data, listed in unknown, not an error.

lookup.vintage names the reference data the answer came from: the same data advisories use for their zcta lists, so a ZIP here and an advisory's zcta agree.

The API can also list every ZIP in a box and return ZIP shapes; the SDK does not offer those yet.