Crate ipwhois 

ipwhois

Official, async Rust client for the ipwhois.io IP Geolocation API.

• ✅ Single and bulk IP lookups (IPv4 and IPv6)
• ✅ Works with both the Free and Paid plans
• ✅ HTTPS by default
• ✅ Localisation, field selection, threat detection, rate info
• ✅ Errors as values — every fallible call returns Result<_, Error>
• ✅ Uniform error categories (api, network, invalid_argument)

Quick start

use ipwhois::{IpWhois, Options};

// Free plan (no API key, ~1 request/second per client IP)
let ipwhois = IpWhois::new();
let info = ipwhois.lookup("8.8.8.8").await?;

// Paid plan (with API key, higher limits, bulk, security data, …)
let ipwhois = IpWhois::with_key("YOUR_API_KEY");
let info = ipwhois
    .lookup_with(
        "8.8.8.8",
        &Options::new().with_lang("en").with_security(true),
    )
    .await?;

// Bulk lookup — up to 100 IPs in one call (paid only)
let list = ipwhois
    .bulk_lookup(["8.8.8.8", "1.1.1.1", "208.67.222.222"])
    .await?;

// HTTPS is enabled by default. Call `.with_ssl(false)` to fall back to HTTP.

Error handling

Every fallible operation returns Result<_, Error>. The error enum exposes three categories — api, network, invalid_argument — and carries the relevant metadata (http_status, plus retry_after on free-plan 429s).

let ipwhois = IpWhois::new();
match ipwhois.lookup("8.8.8.8").await {
    Ok(info) => println!("{} → {}", info.ip.unwrap_or_default(), info.country.unwrap_or_default()),
    Err(Error::Api { http_status: Some(429), retry_after, .. }) => {
        // Rate-limited — `retry_after` is set on the free plan only.
        eprintln!("rate-limited, retry in {:?}s", retry_after);
    }
    Err(e) => eprintln!("Lookup failed ({}): {}", e.error_type(), e.message()),
}

Structs

Connection

Currency

Flag

IpWhois

Async client for the ipwhois.io IP Geolocation API.

LookupResponse

Successful lookup response, or a per-IP entry inside a bulk response.

Options

Options accepted by lookup calls and by the client as defaults.

Rate

Rate-limit block. Returned only when the rate option is enabled and the API key has Basic+ access.

Security

Threat-detection block. Returned only when the security option is enabled and the API key has Business+ access.

Timezone

Enums

Error

All errors returned by this crate.

Constants

BULK_LIMIT

Maximum number of IP addresses allowed in a single bulk request.

HOST_FREE

Free-plan endpoint host (used when no API key is provided).

HOST_PAID

Paid-plan endpoint host (used when an API key is provided).

SUPPORTED_LANGUAGES

Languages supported by the lang option.

VERSION

Library version, used in the default User-Agent header.