Crate zipcodes 

Query U.S. zipcodes without SQLite.

The full zipcode dataset is embedded into the binary at compile time via include_bytes! and lazily decompressed/parsed on first access, making this crate suitable for constrained environments (AWS Lambda, containers) with no runtime file I/O.

Structs

Zipcode

A record in the zipcode database.

Enums

Error

Describes different types of errors with supplied zipcodes during parsing.

Constants

FIELD_ORDER

Canonical field order of records in zips.json and of the dicts returned by the Python package. This is the base CSV’s historical column order — not alphabetical (the struct above is declared alphabetically; serde matches by name, so the two need only agree on the field set, not its order).

Functions

clean_prefix

Validate a partial zipcode (prefix or fragment): after trimming, require 1–5 ASCII digits. Longer input is Error::InvalidFormat; non-digits are Error::InvalidCharacters. Empty input is also rejected as Error::InvalidFormat (the Python shim guards it earlier with a TypeError), so this never returns Ok("").

clean_zipcode

Validate and normalize a full zipcode ("#####", "#####-####", or "##### ####"): trim surrounding whitespace, require at least five characters, then take the first five and require them to be ASCII digits.

contains

Return the zipcodes whose zip_code contains the supplied fragment anywhere.

database

Borrow the full embedded zipcode database without copying it.

filter_by

Using a supplied list of filter-functions, return a filtered list of zipcodes.

filter_by_coordinates

Return the zipcodes within radius_in_miles of the supplied coordinates.

filter_by_fields

Return the zipcodes whose named fields equal the supplied JSON values.

haversine

Calculate the great circle distance in miles between two points on the earth, specified in decimal degrees.

is_real

Returns true if the supplied zipcode exists in the database.

list_all

Retrieve a list of all zipcodes in the database.

matching

Determine whether a supplied zipcode matches any existing zipcode. The supplied zipcode must be of the format: “#####”, “#####-####”, or “##### ####”.

similar_to

Return the zipcodes whose zip_code starts with the supplied prefix.

Type Aliases

Result

A result type where the error is an Error.