### Initialize Shodan Client and Get API Info (Rust)

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Initializes the Shodan client with an API key and retrieves account API information, including plan details and credit balances. Requires the 'shodan_client' and 'tokio' crates.

```rust
use shodan_client::*;

#[tokio::main] async fn main() -> Result<(), Error> {
    // Create client with your API key from shodan.io
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Verify connection by checking API info
    let api_info = client.get_api_info().await?;
    println!("Plan: {}", api_info.plan);
    println!("Query credits: {}", api_info.query_credits);
    println!("Scan credits: {}", api_info.scan_credits);

    Ok(())
}
```

--------------------------------

### Utility: Get My IP and HTTP Headers

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Utility endpoints to get your public IP address and see how your HTTP headers appear to Shodan. Useful for debugging and understanding your network's visibility.

```APIDOC
## Utility Endpoints

### Description
Provides utility functions to retrieve your public IP address and inspect the HTTP headers Shodan sees from your requests. These are helpful for diagnostics and understanding your Shodan footprint.

### Method
GET

### Endpoints
- `/tools/myip` (for getting your IP address)
- `/tools/httpheaders` (for getting HTTP headers)

### Response
#### Success Response (200) for `/tools/myip`
- **IP Address** (string) - Your public IP address.

#### Success Response (200) for `/tools/httpheaders`
- **HTTP Headers Map** (object) - A map where keys are header names (strings) and values are their corresponding header values (strings).

### Response Example for `/tools/myip`
```json
"192.0.2.1"
```

### Response Example for `/tools/httpheaders`
```json
{
  "User-Agent": "Shodan/1.0",
  "Accept-Language": "en-US,en;q=0.5",
  ...
}
```
```

--------------------------------

### Fetch Shodan Account Details in Rust

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Shows how to retrieve account details from the Shodan API using the ShodanClient. This example uses an async call and unwraps the result, which should be handled with proper error management in production code.

```rust
use shodan_client::*

// Assuming 'client' is an initialized ShodanClient instance
let account_details = client.get_account_profile().await.unwrap();
println!("Account Details: {:?}", account_details);
```

--------------------------------

### Batch DNS Resolution with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Demonstrates resolving multiple hostnames to their corresponding IP addresses in a batch using the Shodan API and Rust. This is an efficient way to get IP information for a list of domains. It requires the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let resolved = client.dns_resolve(vec![
        String::from("google.com"),
        String::from("facebook.com"),
        String::from("github.com"),
    ]).await?;

    for (hostname, ip) in resolved {
        match ip {
            Some(addr) => println!("{} -> {}", hostname, addr),
            None => println!("{} -> Not resolved", hostname),
        }
    }
    // Output:
    // google.com -> 142.250.185.238
    // facebook.com -> 157.240.1.35
    // github.com -> 140.82.121.4

    Ok(())
}
```

--------------------------------

### Get Account Profile

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Retrieves detailed information about the user's Shodan account.

```APIDOC
## GET /account/profile

### Description
Retrieves detailed information about the user's Shodan account, including membership status, available credits, and account creation date.

### Method
GET

### Endpoint
/account/profile

### Parameters
#### Query Parameters
- **key** (string) - Required - Your Shodan API key.

### Request Example
```rust
use shodan_client::*

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));
    let profile = client.get_account_profile().await?;
    println!("Member: {}", profile.member);
    println!("Credits: {}", profile.credits);
    println!("Created: {}", profile.created);
    if let Some(name) = profile.display_name {
        println!("Display name: {}", name);
    }
    Ok(())
}
```

### Response
#### Success Response (200)
- **member** (boolean) - Indicates if the user is a paid member.
- **credits** (integer) - The number of available credits.
- **created** (string) - The date the account was created.
- **display_name** (string, optional) - The user's display name.

#### Response Example
```json
{
  "member": true,
  "credits": 1000,
  "created": "2023-01-01T10:00:00Z",
  "display_name": "ShodanUser"
}
```
```

--------------------------------

### Get Public IP and HTTP Headers with Shodan Client

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Utility functions to retrieve the client's public IP address and to inspect how HTTP headers are presented to Shodan. These are useful for debugging and understanding network visibility. Requires a Shodan API key.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Get your public IP address
    let my_ip = client.get_my_ip().await?;
    println!("My public IP: {}", my_ip);

    // See HTTP headers as Shodan sees them
    let headers = client.get_http_headers().await?;
    println!("\nHTTP Headers:");
    for (key, value) in headers {
        println!("  {}: {}", key, value);
    }

    Ok(())
}
```

--------------------------------

### Host Count

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Gets the total number of results matching a search query without returning individual hosts.

```APIDOC
## GET /shodan/host/count

### Description
Gets the total number of results matching a search query without returning individual hosts. Useful for statistics and monitoring.

### Method
GET

### Endpoint
/shodan/host/count

### Parameters
#### Query Parameters
- **key** (string) - Required - Your Shodan API key.
- **query** (string) - Required - The search query string.
- **facets** (string, optional) - Comma-separated list of facets for aggregation (e.g., "os,port").

### Request Example
```rust
use shodan_client::*

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));
    let count = client.host_count(String::from("port:22 country:US"), Some("os,port")).await?;
    println!("Total SSH servers in US: {}", count.total);
    if let Some(facets) = count.facets {
        if let Some(os_facets) = facets.get("os") {
            println!("\nOperating systems:");
            for os in os_facets.iter().take(10) {
                println!("  {}: {}", os.value, os.count);
            }
        }
    }
    Ok(())
}
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of results matching the query.
- **facets** (object, optional) - Aggregated statistics based on the requested facets.

#### Response Example
```json
{
  "total": 50000,
  "facets": {
    "os": [
      {
        "value": "Linux",
        "count": 30000
      },
      {
        "value": "Windows",
        "count": 15000
      }
    ]
  }
}
```
```

--------------------------------

### Query Directory Tags API

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Get popular tags used in the saved queries directory. This endpoint provides insights into the most common tags associated with saved searches.

```APIDOC
## GET /directory/query/tags

### Description
Get popular tags used in the saved queries directory. Returns a list of tags and the count of saved queries associated with each tag.

### Method
GET

### Endpoint
/directory/query/tags

### Query Parameters
- **limit** (integer) - Optional - The maximum number of tags to return.

### Response
#### Success Response (200)
- **matches** (array) - A list of tag objects, each containing:
    - **value** (string) - The tag name.
    - **count** (integer) - The number of saved queries using this tag.

### Response Example
```json
{
  "matches": [
    {
      "value": "webcam",
      "count": 500
    },
    {
      "value": "industrial",
      "count": 350
    }
  ]
}
```
```

--------------------------------

### Get Popular Tags from Shodan Query Directory

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Retrieves a list of the most popular tags used within the Shodan saved queries directory. The results include the tag value and the count of queries associated with it. Supports pagination.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let tags = client.directory_query_tags(Some(20)).await?;

    if let ShodanClientResponse::Response(result) = tags {
        println!("Popular tags:");
        for tag in result.matches {
            println!("  {}: {} queries", tag.value, tag.count);
        }
    }

    Ok(())
}
```

--------------------------------

### Create ShodanClient Instance in Rust

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Demonstrates how to initialize a ShodanClient using an API key. This is the first step to interacting with the Shodan API through the library. Ensure you have a valid API key from shodan.io.

```rust
use shodan_client::*

let client = ShodanClient::new(String::from("API-KEY-GOES-HERE"));
```

--------------------------------

### Shodan Client Initialization and API Info

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Initializes the Shodan client with an API key and retrieves account information.

```APIDOC
## POST /api/info

### Description
Initializes the Shodan client with an API key and retrieves account information such as plan details and credit balances.

### Method
GET

### Endpoint
/api/info

### Parameters
#### Query Parameters
- **key** (string) - Required - Your Shodan API key.

### Request Example
```rust
use shodan_client::*

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));
    let api_info = client.get_api_info().await?;
    println!("Plan: {}", api_info.plan);
    println!("Query credits: {}", api_info.query_credits);
    println!("Scan credits: {}", api_info.scan_credits);
    Ok(())
}
```

### Response
#### Success Response (200)
- **plan** (string) - The current Shodan subscription plan.
- **query_credits** (integer) - The number of available query credits.
- **scan_credits** (integer) - The number of available scan credits.

#### Response Example
```json
{
  "plan": "free",
  "query_credits": 100,
  "scan_credits": 50
}
```
```

--------------------------------

### List Shodan Host Search Facets and Filters with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Shows how to retrieve available facets and filters for constructing Shodan search queries using Rust. This is useful for understanding the searchable attributes and refining search strategies. It depends on the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Get list of available facets
    let facets = client.host_facets().await?;
    println!("Available facets: {:?}", facets);
    // e.g., ["asn", "city", "country", "device", "domain", "ip", "isp", "org", "os", ...]

    // Get list of available search filters
    let filters = client.host_filters().await?;
    println!("Available filters: {:?}", filters);
    // e.g., ["asn", "city", "country", "cpe", "device", "geo", "hash", "has_ipv6", ...]

    Ok(())
}
```

--------------------------------

### Build Complex Shodan Search Queries with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Demonstrates building complex Shodan search queries programmatically using a type-safe builder pattern in Rust. This method allows for precise filtering by ports, products, and SSL certificates, improving search accuracy. It requires the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Build a complex query using the builder pattern
    let query = SearchQueryBuilder::default()
        .query("apache")
        .port(443)
        .port(8443)
        .product("Apache")
        .ssl(|ssl| ssl
            .cert_subject_cn("example.com")
            .cert_subject_cn("*.example.com")
        )
        .build();

    // query = "apache port:443,8443 product:Apache cert.subject.cn:example.com,*.example.com"
    println!("Built query: {}", query);

    let results = client.host_search(query, None, None, Some(true)).await?;
    println!("Found {} results", results.total);

    Ok(())
}
```

--------------------------------

### Parse Shodan Search Query Tokens with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Demonstrates parsing a Shodan search query into its constituent tokens using Rust. This helps visualize how Shodan interprets filters and attributes within a query string. It requires the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let tokens = client.host_tokens(String::from("Raspbian port:22")).await?;

    println!("Parsed string: {}", tokens.string);
    println!("Filters: {:?}", tokens.filters);
    println!("Attributes: {:?}", tokens.attributes);
    if !tokens.errors.is_empty() {
        println!("Errors: {:?}", tokens.errors);
    }

    Ok(())
}
```

--------------------------------

### Reverse DNS Lookup for IP Addresses with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Shows how to perform reverse DNS lookups for a list of IP addresses to find their associated hostnames using Rust and the Shodan API. This is useful for identifying the domain names linked to specific IP addresses. It depends on the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let reverse = client.dns_reverse(vec![
        String::from("8.8.8.8"),
        String::from("1.1.1.1"),
    ]).await?;

    for (ip, hostnames) in reverse {
        println!("{} -> {:?}", ip, hostnames);
    }
    // Output:
    // 8.8.8.8 -> ["dns.google"]
    // 1.1.1.1 -> ["one.one.one.one"]

    Ok(())
}
```

--------------------------------

### Query Directory API

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Browse the community-contributed saved searches directory on Shodan. You can list popular queries, sort them, and paginate the results.

```APIDOC
## GET /directory/query

### Description
Browse the community-contributed saved searches directory on Shodan. Allows listing popular queries with options for pagination, sorting, and order.

### Method
GET

### Endpoint
/directory/query

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **sort** (string) - Optional - The field to sort the results by (e.g., 'votes').
- **order** (string) - Optional - The order of sorting ('asc' or 'desc').

### Response
#### Success Response (200)
- **total** (integer) - The total number of saved queries.
- **matches** (array) - A list of saved query objects, each containing:
    - **title** (string) - The title of the saved query.
    - **query** (string) - The Shodan query string.
    - **votes** (integer) - The number of votes the query has received.
    - **tags** (array of strings) - Tags associated with the query.

### Response Example
```json
{
  "total": 1500,
  "matches": [
    {
      "title": "Webcams in USA",
      "query": "webcam country:us",
      "votes": 120,
      "tags": ["webcam", "video", "usa"]
    }
  ]
}
```
```

--------------------------------

### Retrieve DNS Domain Information with Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Explains how to fetch all DNS records and subdomains for a given domain using the Shodan API in Rust. This function allows optional filtering by history, record type, and pagination. It utilizes the `shodan-client` and `tokio` crates.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let dns_info = client.dns_domain(
        String::from("google.com"),
        None,  // history: include historical DNS data
        None,  // dns_type: filter by record type (A, AAAA, CNAME, etc.)
        None,  // page: for pagination
    ).await?;

    println!("Domain: {}", dns_info.domain);
    println!("Tags: {:?}", dns_info.tags);
    println!("More results available: {}", dns_info.more);

    println!("\nSubdomains:");
    for subdomain in dns_info.subdomains.iter().take(10) {
        println!("  {}", subdomain);
    }

    println!("\nDNS Records:");
    for record in dns_info.data.iter().take(10) {
        println!("  {} {} -> {} (last seen: {})",
            record.subdomain, record.item_type, record.value, record.last_seen);
    }

    Ok(())
}
```

--------------------------------

### Host Search

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Searches Shodan's database for hosts matching a query string.

```APIDOC
## GET /shodan/host/search

### Description
Searches Shodan's database for hosts matching a query string. Supports optional facets for aggregated statistics and pagination.

### Method
GET

### Endpoint
/shodan/host/search

### Parameters
#### Query Parameters
- **key** (string) - Required - Your Shodan API key.
- **query** (string) - Required - The search query string.
- **facets** (string, optional) - Comma-separated list of facets for aggregation (e.g., "country,org").
- **page** (integer, optional) - The page number of the search results.
- **minifi** (boolean, optional) - Whether to minimize the response size.

### Request Example
```rust
use shodan_client::*

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));
    let results = client.host_search(String::from("apache"), Some("country,org"), Some(1), Some(true)).await?;
    println!("Total results: {}", results.total);
    for host in results.matches.iter().take(5) {
        println!("---");
        println!("IP: {}", host.ip_str);
        println!("Port: {}", host.port);
        println!("Organization: {:?}", host.org);
        if let Some(product) = &host.product {
            println!("Product: {}", product);
        }
    }
    if let Some(facets) = results.facets {
        if let Some(countries) = facets.get("country") {
            println!("\nTop countries:");
            for facet in countries.iter().take(5) {
                println!("  {}: {}", facet.value, facet.count);
            }
        }
    }
    Ok(())
}
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of results matching the query.
- **matches** (array) - A list of host matches.
  - **ip_str** (string) - The IP address of the host.
  - **port** (integer) - The port number.
  - **org** (string, optional) - The organization associated with the host.
  - **product** (string, optional) - The product detected on the host.
- **facets** (object, optional) - Aggregated statistics based on the requested facets.

#### Response Example
```json
{
  "total": 15000,
  "matches": [
    {
      "ip_str": "1.2.3.4",
      "port": 80,
      "org": "Example Corp",
      "product": "Apache httpd"
    }
  ],
  "facets": {
    "country": [
      {
        "value": "US",
        "count": 5000
      }
    ]
  }
}
```
```

--------------------------------

### Run Shodan API Client Tests with API Key

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

This command demonstrates how to execute the test suite for the Shodan API client. It requires setting the SHODAN_TEST_KEY environment variable with your Shodan API key before running the cargo test command. Note that running tests may consume API credits and is subject to Shodan API rate limiting.

```shell
$ SHODAN_TEST_KEY=<API-KEY-GOES-HERE> cargo test

```

--------------------------------

### Handle Shodan API Errors in Rust

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Demonstrates how to handle various error types returned by the Shodan API client library. This includes specific handling for Shodan API errors (like invalid keys), network issues (Reqwest errors), and URL parsing problems.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() {
    let client = ShodanClient::new(String::from("invalid_key"));

    match client.get_api_info().await {
        Ok(info) => {
            println!("Plan: {}", info.plan);
        }
        Err(Error::Shodan(msg)) => {
            // API-level error (rate limiting, invalid key, insufficient credits)
            eprintln!("Shodan API error: {}", msg);
        }
        Err(Error::Reqwest(e)) => {
            // Network/HTTP error (connection failed, SSL error, etc.)
            eprintln!("Network error: {}", e);
        }
        Err(Error::UrlParse(e)) => {
            // URL construction error (shouldn't happen in normal use)
            eprintln!("URL parse error: {}", e);
        }
    }
}
```

--------------------------------

### Search Shodan Hosts with Facets (Rust)

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Searches Shodan's database for hosts matching a query string and optionally returns aggregated statistics (facets) for specified fields like country or organization. Supports pagination and response size minimization.

```rust
use shodan_client::*;

#[tokio::main] async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Search for Apache servers
    let results = client.host_search(
        String::from("apache"),
        Some("country,org"),  // facets for aggregation
        Some(1),              // page number
        Some(true),           // minifi to reduce response size
    ).await?;

    println!("Total results: {}", results.total);

    for host in results.matches.iter().take(5) {
        println!("---");
        println!("IP: {}", host.ip_str);
        println!("Port: {}", host.port);
        println!("Organization: {:?}", host.org);
        if let Some(product) = &host.product {
            println!("Product: {}", product);
        }
    }

    // Print facet results
    if let Some(facets) = results.facets {
        if let Some(countries) = facets.get("country") {
            println!("\nTop countries:");
            for facet in countries.iter().take(5) {
                println!("  {}: {}", facet.value, facet.count);
            }
        }
    }

    Ok(())
}
```

--------------------------------

### List Shodan Scanning Ports and Protocols

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Fetches information about the ports and protocols that Shodan crawlers actively scan. This includes a list of all scanned ports and a description of supported protocols for on-demand scans. Requires a Shodan API key.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Get list of ports Shodan scans
    let ports = client.get_scanning_ports().await?;
    if let ShodanClientResponse::Response(port_list) = ports {
        println!("Shodan scans {} ports", port_list.len());
        println!("Sample ports: {:?}", &port_list[..10.min(port_list.len())]);
    }

    // Get supported protocols for on-demand scans
    let protocols = client.get_scanning_protocols().await?;
    if let ShodanClientResponse::Response(proto_map) = protocols {
        println!("\nSupported scan protocols:");
        for (protocol, description) in proto_map.iter().take(10) {
            println!("  {}: {}", protocol, description);
        }
    }

    Ok(())
}
```

--------------------------------

### List Popular Shodan Saved Queries

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Fetches and displays a list of popular saved queries from the Shodan directory. It allows sorting by votes in descending order and paginates results. Requires a Shodan API key.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // List popular queries
    let queries = client.directory_query(
        Some(1),                         // page
        Some(String::from("votes")),     // sort by votes
        Some(String::from("desc")),      // descending order
    ).await?;

    if let ShodanClientResponse::Response(result) = queries {
        println!("Total saved queries: {}", result.total);

        for query in result.matches.iter().take(5) {
            println!("---");
            println!("Title: {}", query.title);
            println!("Query: {}", query.query);
            println!("Votes: {}", query.votes);
            println!("Tags: {:?}", query.tags);
        }
    }

    Ok(())
}
```

--------------------------------

### Scanning Ports and Protocols API

Source: https://context7.com/vswarte/shodan-rs/llms.txt

List ports and protocols that Shodan crawlers scan for. This includes both a list of scanned ports and supported protocols for on-demand scans.

```APIDOC
## GET /ports

### Description
List ports and protocols that Shodan crawlers scan for. This endpoint provides two sets of information: a list of all scanned ports and a map of supported protocols for on-demand scans.

### Method
GET

### Endpoint
/ports

### Response
#### Success Response (200)
- **Ports List**: An array of integers representing the ports Shodan scans.
- **Protocols Map**: A map where keys are protocol names (strings) and values are their descriptions (strings).

### Response Example
```json
{
  "Ports List": [21, 22, 23, 80, 443, ...],
  "Protocols Map": {
    "http": "Hypertext Transfer Protocol",
    "https": "Hypertext Transfer Protocol Secure",
    "ftp": "File Transfer Protocol",
    ...
  }
}
```
```

--------------------------------

### Search Shodan Saved Queries by Keyword

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Searches the Shodan saved queries directory for entries matching a specific keyword, such as 'webcam'. This function returns a paginated list of matching queries. Requires a Shodan API key.

```rust
use shodan_client::*;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let results = client.directory_query_search(
        String::from("webcam"),
        None,  // page
    ).await?;

    if let ShodanClientResponse::Response(result) = results {
        println!("Found {} webcam-related queries", result.total);

        for query in result.matches.iter().take(5) {
            println!("{}: {}", query.title, query.query);
        }
    }

    Ok(())
}
```

--------------------------------

### Host IP Lookup

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Retrieves detailed information about a specific IP address.

```APIDOC
## GET /shodan/host/{ip}

### Description
Retrieves detailed information about a specific IP address, including open ports, services, geolocation, and organization data.

### Method
GET

### Endpoint
/shodan/host/{ip}

### Parameters
#### Path Parameters
- **ip** (string) - Required - The IP address to look up.

#### Query Parameters
- **key** (string) - Required - Your Shodan API key.
- **history** (boolean, optional) - Whether to include historical banner data.
- **minifi** (boolean, optional) - Whether to minimize the response size.

### Request Example
```rust
use shodan_client::*

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));
    let host = client.host_ip(String::from("8.8.8.8"), None, None).await?;
    println!("IP: {}", host.ip_str);
    println!("Ports: {:?}", host.ports);
    println!("Hostnames: {:?}", host.hostnames);
    println!("Organization: {:?}", host.org);
    println!("ISP: {:?}", host.isp);
    println!("Country: {:?}", host.country_name);
    println!("City: {:?}", host.city);
    Ok(())
}
```

### Response
#### Success Response (200)
- **ip_str** (string) - The IP address.
- **ports** (array) - A list of open ports.
- **hostnames** (array) - A list of hostnames associated with the IP.
- **org** (string, optional) - The organization associated with the IP.
- **isp** (string, optional) - The ISP of the IP address.
- **country_name** (string, optional) - The name of the country.
- **city** (string, optional) - The name of the city.

#### Response Example
```json
{
  "ip_str": "8.8.8.8",
  "ports": [53, 80, 443],
  "hostnames": ["dns.google"],
  "org": "Google LLC",
  "isp": "Google",
  "country_name": "United States",
  "city": "Mountain View"
}
```
```

--------------------------------

### Error Handling

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Information on how the shodan-rs library handles errors, including API-specific errors, network issues, and URL parsing problems.

```APIDOC
## Error Handling

### Description
The `shodan-rs` library utilizes a custom `Error` enum to manage various failure scenarios. This includes errors originating from the Shodan API itself (like invalid keys or rate limits), network-related issues encountered during requests, and potential problems with URL construction.

### Error Types
- **`Error::Shodan(String)`**: Represents errors returned by the Shodan API, such as invalid API keys, insufficient credits, or rate limiting.
- **`Error::Reqwest(reqwest::Error)`**: Wraps errors from the underlying `reqwest` HTTP client, covering network connectivity issues, SSL errors, and other transport-level problems.
- **`Error::UrlParse(url::ParseError)`**: Indicates an error during the construction or parsing of URLs, which should be rare in typical usage but is included for completeness.

### Example Usage
```rust
use shodan_client::Error;

match some_api_call().await {
    Ok(data) => { /* Process data */ },
    Err(Error::Shodan(msg)) => eprintln!("Shodan API error: {}", msg),
    Err(Error::Reqwest(e)) => eprintln!("Network error: {}", e),
    Err(Error::UrlParse(e)) => eprintln!("URL parse error: {}", e),
    Err(e) => eprintln!("An unexpected error occurred: {}", e), // Catch-all for other potential errors
}
```
```

--------------------------------

### HTTP Headers Tool API

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Retrieves HTTP headers for a given URL.

```APIDOC
## GET /tools/httpheaders

### Description
Retrieves the HTTP headers sent by the Shodan service when connecting to a specified URL.

### Method
GET

### Endpoint
/tools/httpheaders

### Parameters
#### Path Parameters
None

#### Query Parameters
- **url** (string) - Required - The URL to fetch headers from.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **headers** (object) - An object containing the HTTP headers.

#### Response Example
{
  "headers": {
    "Content-Type": "text/html",
    "Server": "nginx"
  }
}
```

--------------------------------

### Search Query Directory API

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Search for saved queries in the directory by keyword. This endpoint allows you to find relevant saved searches based on specific terms.

```APIDOC
## GET /directory/query/search

### Description
Search for saved queries in the directory by keyword. Returns a list of saved searches that match the provided search term.

### Method
GET

### Endpoint
/directory/query/search

### Query Parameters
- **query** (string) - Required - The keyword to search for in the saved queries directory.
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **total** (integer) - The total number of matching saved queries.
- **matches** (array) - A list of saved query objects matching the search term.

### Response Example
```json
{
  "total": 50,
  "matches": [
    {
      "title": "Webcam Access",
      "query": "webcam",
      "votes": 30,
      "tags": ["webcam", "security"]
    }
  ]
}
```
```

--------------------------------

### API Information API

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Retrieves general information about the Shodan API.

```APIDOC
## GET /api-info

### Description
Provides general information about the Shodan API, including available services and usage limits.

### Method
GET

### Endpoint
/api-info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **api_version** (string) - The current version of the API.
- **https_enabled** (boolean) - Indicates if HTTPS is enabled.
- **server_time** (string) - The current time on the Shodan server.
- **plan** (string) - The user's current subscription plan.

#### Response Example
{
  "api_version": "2022-03-01",
  "https_enabled": true,
  "server_time": "2023-10-27T10:30:00Z",
  "plan": "free"
}
```

--------------------------------

### Retrieve Shodan Account Profile (Rust)

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Fetches the user's Shodan account profile, including membership status, available credits, account creation date, and optional display name. This function requires a valid Shodan API key.

```rust
use shodan_client::*;

#[tokio::main] async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    let profile = client.get_account_profile().await?;

    println!("Member: {}", profile.member);
    println!("Credits: {}", profile.credits);
    println!("Created: {}", profile.created);
    if let Some(name) = profile.display_name {
        println!("Display name: {}", name);
    }

    Ok(())
}
```

--------------------------------

### DNS Resolve API

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Resolves hostnames to IP addresses.

```APIDOC
## GET /dns/resolve

### Description
Resolves one or more hostnames to their corresponding IP addresses.

### Method
GET

### Endpoint
/dns/resolve

### Parameters
#### Path Parameters
None

#### Query Parameters
- **hostnames** (string) - Required - A comma-separated list of hostnames to resolve.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **results** (object) - An object mapping hostnames to their resolved IP addresses.
  - **hostname** (string) - The resolved IP address for the hostname.

#### Response Example
{
  "results": {
    "example.com": "192.0.2.1",
    "www.example.com": "192.0.2.2"
  }
}
```

--------------------------------

### Directory API Endpoints

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Endpoints for querying Shodan's directory of services and hosts.

```APIDOC
## GET /shodan/query

### Description
Retrieves a list of popular Shodan queries.

### Method
GET

### Endpoint
/shodan/query

### Response
#### Success Response (200)
- **queries** (array) - A list of popular query strings.

#### Response Example
```json
[
  "http.title:index of",
  "ssl:apache"
]
```
```

```APIDOC
## GET /shodan/query/search

### Description
Searches for hosts based on a query string and returns matching results.

### Method
GET

### Endpoint
/shodan/query/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **matches** (array) - A list of host objects matching the query.

#### Response Example
```json
[
  {
    "ip_str": "1.1.1.1",
    "port": 80,
    "org": "Cloudflare, Inc."
  }
]
```
```

```APIDOC
## GET /shodan/query/tags

### Description
Retrieves a list of tags that can be used in Shodan queries.

### Method
GET

### Endpoint
/shodan/query/tags

### Response
#### Success Response (200)
- **tags** (array) - A list of available query tags.

#### Response Example
```json
[
  "http",
  "ssl",
  "ftp"
]
```
```

--------------------------------

### DNS Reverse Lookup API

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Resolves IP addresses to hostnames.

```APIDOC
## GET /dns/reverse

### Description
Resolves one or more IP addresses to their corresponding hostnames.

### Method
GET

### Endpoint
/dns/reverse

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ips** (string) - Required - A comma-separated list of IP addresses to resolve.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **results** (object) - An object mapping IP addresses to their resolved hostnames.
  - **ip** (string) - The resolved hostname for the IP address.

#### Response Example
{
  "results": {
    "192.0.2.1": "example.com",
    "192.0.2.2": "www.example.com"
  }
}
```

--------------------------------

### Perform Shodan Host IP Lookup (Rust)

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Retrieves detailed information for a specific IP address from Shodan, including open ports, hostnames, organization, ISP, and geolocation. Optional parameters allow including historical data or minimizing response size.

```rust
use shodan_client::*;

#[tokio::main] async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Lookup Google's DNS server
    let host = client.host_ip(
        String::from("8.8.8.8"),
        None,    // history: include historical banners
        None,    // minifi: minimize response size
    ).await?;

    println!("IP: {}", host.ip_str);
    println!("Ports: {:?}", host.ports);
    println!("Hostnames: {:?}", host.hostnames);
    println!("Organization: {:?}", host.org);
    println!("ISP: {:?}", host.isp);
    println!("Country: {:?}", host.country_name);
    println!("City: {:?}", host.city);

    Ok(())
}
```

--------------------------------

### Bulk Data API Endpoints

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Endpoints for retrieving bulk data from Shodan.

```APIDOC
## GET /shodan/data

### Description
Retrieves a list of available bulk data datasets.

### Method
GET

### Endpoint
/shodan/data

### Response
#### Success Response (200)
- **datasets** (array) - A list of available dataset names.

#### Response Example
```json
[
  "http-headers",
  "ssl"
]
```
```

```APIDOC
## GET /shodan/data/{dataset}

### Description
Retrieves bulk data for a specific dataset.

### Method
GET

### Endpoint
/shodan/data/{dataset}

### Parameters
#### Path Parameters
- **dataset** (string) - Required - The name of the dataset to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The bulk data for the specified dataset.

#### Response Example
```json
{
  "data": [
    {
      "ip_str": "1.1.1.1",
      "port": 80,
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Organization API Endpoints

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Endpoints for managing organization-level settings and members.

```APIDOC
## GET /org

### Description
Retrieves information about the current organization.

### Method
GET

### Endpoint
/org

### Response
#### Success Response (200)
- **name** (string) - The name of the organization.
- **members** (array) - A list of organization members.

#### Response Example
```json
{
  "name": "Example Corp",
  "members": [
    "user1@example.com",
    "user2@example.com"
  ]
}
```
```

```APIDOC
## PUT /org/member/{user}

### Description
Adds a user as a member to the organization.

### Method
PUT

### Endpoint
/org/member/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or email of the user to add.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "User added to organization successfully."
}
```
```

```APIDOC
## DELETE /org/member/{user}

### Description
Removes a user from the organization.

### Method
DELETE

### Endpoint
/org/member/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or email of
```

--------------------------------

### DNS Domain Lookup API

Source: https://github.com/vswarte/shodan-rs/blob/main/README.md

Retrieves DNS records for a specific domain.

```APIDOC
## GET /dns/domain/{domain}

### Description
Retrieves DNS records (e.g., A, MX, NS) for a specified domain.

### Method
GET

### Endpoint
/dns/domain/{domain}

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name to query.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **records** (array) - A list of DNS records associated with the domain.
  - **type** (string) - The type of DNS record (e.g., A, MX).
  - **value** (string) - The value of the DNS record.

#### Response Example
{
  "records": [
    {
      "type": "A",
      "value": "192.0.2.1"
    },
    {
      "type": "MX",
      "value": "mail.example.com"
    }
  ]
}
```

--------------------------------

### Count Shodan Hosts with Facets (Rust)

Source: https://context7.com/vswarte/shodan-rs/llms.txt

Retrieves the total count of hosts matching a specific Shodan query and provides aggregated statistics (facets) for fields like operating system or port. This is useful for statistical analysis without fetching individual host data.

```rust
use shodan_client::*;

#[tokio::main] async fn main() -> Result<(), Error> {
    let client = ShodanClient::new(String::from("YOUR_API_KEY"));

    // Count hosts matching query with facets
    let count = client.host_count(
        String::from("port:22 country:US"),
        Some("os,port"),
    ).await?;

    println!("Total SSH servers in US: {}", count.total);

    if let Some(facets) = count.facets {
        if let Some(os_facets) = facets.get("os") {
            println!("\nOperating systems:");
            for os in os_facets.iter().take(10) {
                println!("  {}: {}", os.value, os.count);
            }
        }
    }

    Ok(())
}
```