zipcodestack-rs

Idiomatic Rust client for the zipcodestack.com API. Website: zipcodestack

Features

• Status endpoint: check API health and quota
• Zip/postal code search
• Distance between two zip codes (miles or kilometers)
• Flexible authentication via header or query parameter

Installation

Add to your Cargo.toml:

[dependencies]
zipcodestack = { path = "." }
tokio = { version = "1", features = ["full"] }

Usage

use zipcodestack::{ZipCodeStackClient, AuthMethod, DistanceUnit};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ZipCodeStackClient::builder("YOUR_API_KEY")
        .with_auth_method(AuthMethod::Header)
        .build();

    // API Status
    let status = client.status().await?;
    println!("API up? {:?}", status.up);

    // Search zip code
    let info = client.search_zip("90210", Some("US")).await?;
    println!("{} {:?} {:?}", info.zip_code.unwrap_or_default(), info.city, info.state_code);

    // Distance
    let d = client.distance_between("90210", "10001", Some(DistanceUnit::Miles)).await?;
    println!("Distance (mi): {:?}", d.distance_miles);

    Ok(())
}

Authentication

According to the official docs, you can authenticate via HTTP headers or GET parameters. This client supports both:

• Header: apikey: <API_KEY> (default)
• Query param: ?apikey=<API_KEY>

You can switch using the builder:

let client = ZipCodeStackClient::builder("YOUR_API_KEY")
    .with_auth_method(AuthMethod::QueryParam)
    .build();

Endpoints

• Status: GET /status
• Search: GET /search?zip_code=90210&country=US
• Distance: GET /distance?from=90210&to=10001&unit=miles

Links

License

MIT