# BigDataCloud Rust SDK

[![Crates.io](https://img.shields.io/crates/v/bigdatacloud)](https://crates.io/crates/bigdatacloud)
[![Docs.rs](https://docs.rs/bigdatacloud/badge.svg)](https://docs.rs/bigdatacloud)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Official Rust SDK for [BigDataCloud](https://www.bigdatacloud.com) APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering.

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
bigdatacloud = "1.0.0"
```

## API Key

Get a free API key at [bigdatacloud.com/login](https://www.bigdatacloud.com/login). No credit card required.

```bash
export BIGDATACLOUD_API_KEY=your-key-here
```

## Quick Start

```rust
use bigdatacloud::Client;

fn main() {
    // Reads BIGDATACLOUD_API_KEY from environment
    let client = Client::from_environment().unwrap();

    // IP Geolocation
    let geo = client.ip_geolocation.get(Some("1.1.1.1"), "en").unwrap();
    let loc = geo.location.unwrap();
    let country = geo.country.unwrap();
    println!("{}, {}", loc.city.unwrap_or_default(), country.name.unwrap_or_default());

    // Reverse Geocoding
    let place = client.reverse_geocoding.reverse_geocode(-33.87, 151.21, "en").unwrap();
    println!("{}, {}", place.city.unwrap_or_default(), place.country_name.unwrap_or_default());

    // Phone Validation — country code is required
    let phone = client.verification.validate_phone("+61412345678", "AU").unwrap();
    println!("Valid: {}, Type: {}", phone.is_valid.unwrap_or_default(), phone.line_type.unwrap_or_default());

    // Email Verification
    let email = client.verification.verify_email("user@example.com").unwrap();
    println!("Valid: {}, Disposable: {}", email.is_valid.unwrap_or_default(), email.is_disposable.unwrap_or_default());
}
```

## Confidence Area

The `confidence_area` field may encode multiple polygons. Use the helper:

```rust
use bigdatacloud::confidence_area::split_into_polygons;

let geo = client.ip_geolocation.get_with_confidence_area(Some("1.1.1.1"), "en").unwrap();
let points = geo.confidence_area.as_deref().unwrap_or(&[]);
let polygons = split_into_polygons(points);
for (i, ring) in polygons.iter().enumerate() {
    println!("Ring {}: {} points", i + 1, ring.len());
}
```

## Available APIs

| Client | Methods |
|--------|---------|
| `client.ip_geolocation` | `get`, `get_with_confidence_area`, `get_full`, `get_country_by_ip`, `get_country_info`, `get_all_countries`, `get_hazard_report`, `get_user_risk`, `get_asn_info`, `get_network_by_ip`, `get_timezone_by_iana_id`, `get_timezone_by_ip`, `parse_user_agent` |
| `client.reverse_geocoding` | `reverse_geocode`, `reverse_geocode_with_timezone`, `get_timezone_by_location` |
| `client.verification` | `validate_phone`, `validate_phone_by_ip`, `verify_email` |
| `client.network_engineering` | `get_asn_info_full`, `get_receiving_from`, `get_transit_to`, `get_bgp_prefixes`, `get_networks_by_cidr`, `get_asn_rank_list`, `get_tor_exit_nodes` |

## Running Examples

```bash
export BIGDATACLOUD_API_KEY=your-key-here
cargo run --example ip_geolocation
cargo run --example reverse_geocoding
cargo run --example verification
cargo run --example network_engineering
```

## License

MIT — see [LICENSE](LICENSE).
