Struct IpWhois 

pub struct IpWhois { /* private fields */ }

Async client for the ipwhois.io IP Geolocation API.

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?;

Error handling

Every fallible method returns Result<_, Error>. The error enum carries categories (api, network, invalid_argument) and metadata (http_status, retry_after).

Implementations

impl IpWhois

pub fn new() -> Self

Create a free-plan client (no API key).

The free endpoint (ipwho.is) rate-limits roughly to 1 request per second per client IP. Suitable for low-traffic and non-commercial use.

pub fn with_key(api_key: impl Into<String>) -> Self

Create a paid-plan client using the supplied API key.

Higher limits, plus access to bulk lookups and threat-detection data. Get your key at https://ipwhois.io.

This constructor does not validate the key — an empty or whitespace-only key will produce a client that talks to the paid host with ?key= and let the API itself reject the request. Use try_with_key if you’d rather validate up-front.

pub fn try_with_key(api_key: impl Into<String>) -> Result<Self, Error>

Like with_key, but rejects empty or whitespace-only keys with Error::InvalidArgument before any request is made.

Example

use ipwhois::IpWhois;

// A valid-looking key is accepted (no network call is made here).
IpWhois::try_with_key("MY_KEY").expect("constructed");

// Empty / whitespace-only keys are rejected up-front.
assert!(IpWhois::try_with_key("").is_err());
assert!(IpWhois::try_with_key("   ").is_err());

pub fn with_language(self, lang: impl Into<String>) -> Self

Set the default language used when none is supplied per call. Must be one of SUPPORTED_LANGUAGES.

pub fn with_fields<I, S>(self, fields: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Restrict every response to a fixed set of fields by default.

Include "success" in the list if you rely on the success flag for error checking — when fields is set, the API only returns the fields you ask for.

pub fn with_security(self, enabled: bool) -> Self

Enable or disable the security block on every call by default.

pub fn with_rate(self, enabled: bool) -> Self

Enable or disable the rate block on every call by default.

pub fn with_timeout(self, timeout: Duration) -> Self

Set the per-request total timeout (default: 10 seconds).

pub fn with_connect_timeout(self, timeout: Duration) -> Self

Set the connection timeout (default: 5 seconds).

pub fn with_user_agent(self, ua: impl Into<String>) -> Self

Override the User-Agent header sent with every request.

pub fn with_ssl(self, ssl: bool) -> Self

Toggle HTTPS. On by default; pass false to fall back to HTTP (e.g. in environments without an up-to-date CA bundle).

HTTPS is strongly recommended for production traffic — your API key is sent in the query string and would otherwise travel in clear text.

pub async fn lookup(&self, ip: impl AsRef<str>) -> Result<LookupResponse, Error>

Look up a single IP address using the client’s default options.

Accepts any string-like value (&str, String, &String, Cow<str>, …). To look up the caller’s own public IP, use lookup_self.

Example

let ipwhois = IpWhois::new();
let info = ipwhois.lookup("8.8.8.8").await?;
println!("{} — {}", info.ip.unwrap_or_default(), info.country.unwrap_or_default());

// String / &String also work, no `.as_str()` needed:
let owned = String::from("1.1.1.1");
let info = ipwhois.lookup(&owned).await?;

pub async fn lookup_with( &self, ip: impl AsRef<str>, options: &Options, ) -> Result<LookupResponse, Error>

Look up a single IP address with per-call option overrides.

Per-call options always win over the client’s defaults.

pub async fn lookup_self(&self) -> Result<LookupResponse, Error>

Look up the caller’s own public IP, using the client’s default options.

Equivalent to GET / against the API endpoint, as documented at https://ipwhois.io/documentation.

pub async fn lookup_self_with( &self, options: &Options, ) -> Result<LookupResponse, Error>

Look up the caller’s own public IP with per-call option overrides.

pub async fn bulk_lookup<I, S>( &self, ips: I, ) -> Result<Vec<LookupResponse>, Error>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Look up multiple IP addresses in a single request.

Uses the GET / comma-separated form of the bulk endpoint (https://ipwhois.io/documentation/bulk). Up to BULK_LIMIT addresses per call. Each address counts as one credit. Available on the Business and Unlimited plans only.

Per-IP errors come back inline with success = false for the affected entry; the rest of the batch is still usable. Whole-batch failures (network outage, bad API key, rate limit, …) surface as Err.

Accepts any iterable of string-like items, so &[&str], Vec<String>, &[String], an iterator chain, etc. all work.

pub async fn bulk_lookup_with<I, S>( &self, ips: I, options: &Options, ) -> Result<Vec<LookupResponse>, Error>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Same as bulk_lookup with per-call option overrides.

Trait Implementations

impl Clone for IpWhois

fn clone(&self) -> IpWhois

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IpWhois

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for IpWhois

fn default() -> Self

Returns the “default value” for a type.