Metadata-Version: 2.4
Name: bigdatacloud
Version: 1.1.0
Summary: Official Python SDK for BigDataCloud APIs — IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering
Author-email: BigDataCloud Pty Ltd <support@bigdatacloud.com>
License: MIT
Project-URL: Homepage, https://www.bigdatacloud.com
Project-URL: Documentation, https://www.bigdatacloud.com/docs/sdks
Project-URL: Repository, https://github.com/bigdatacloudapi/bigdatacloud-python
Keywords: ip-geolocation,reverse-geocoding,bigdatacloud,geolocation,network-engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: respx; extra == "dev"
Dynamic: license-file

# BigDataCloud Python SDK

[![PyPI](https://img.shields.io/pypi/v/bigdatacloud)](https://pypi.org/project/bigdatacloud/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Official Python SDK for [BigDataCloud](https://www.bigdatacloud.com) APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering — plus a GraphQL interface for all packages.

## Installation

```bash
pip install bigdatacloud
```

## API Key

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

Store your key in the `BIGDATACLOUD_API_KEY` environment variable:

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

## Quick Start

```python
from bigdatacloud import BigDataCloudClient

# Reads BIGDATACLOUD_API_KEY from environment
client = BigDataCloudClient.from_environment()

# Or pass the key directly
# client = BigDataCloudClient("your-key-here")

# IP Geolocation
geo = client.ip_geolocation.get("1.1.1.1")
print(f"{geo.location.city}, {geo.country.name}")

# Full geolocation with hazard report
full = client.ip_geolocation.get_full("1.1.1.1")
print(f"Security: {full.security_threat}")
print(f"Is Tor:   {full.hazard_report.is_known_as_tor_server}")

# Reverse Geocoding
place = client.reverse_geocoding.reverse_geocode(-33.87, 151.21)
print(f"{place.city}, {place.principal_subdivision}, {place.country_name}")

# Phone Validation
phone = client.verification.validate_phone("+61412345678", "AU")
print(f"Valid: {phone.is_valid}, Type: {phone.line_type}")

# Email Verification
email = client.verification.verify_email("user@example.com")
print(f"Valid: {email.is_valid}, Disposable: {email.is_disposable}")
```

## Context Manager

```python
with BigDataCloudClient.from_environment() as client:
    geo = client.ip_geolocation.get("1.1.1.1")
```

## Confidence Area

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

```python
from bigdatacloud import split_into_polygons

geo = client.ip_geolocation.get_with_confidence_area("1.1.1.1")
polygons = split_into_polygons(geo.confidence_area)
for ring in polygons:
    print(f"Polygon with {len(ring)} points")
```

## GraphQL

BigDataCloud is the only IP geolocation provider with a GraphQL interface. Use the fluent builders to select exactly the fields you need:

```python
# Select only city, country flag, and confidence
result = client.graphql.ip_geolocation.ip_data("1.1.1.1",
    lambda q: q.locality().country(lambda c: c.flag_emoji()).confidence())

print(result["locality"]["city"])

# Reverse geocoding with timezone
loc = client.graphql.reverse_geocoding.location_data(-33.87, 151.21,
    lambda q: q.locality().country().timezone())

# Phone & Email
email = client.graphql.verification.email_verification("user@example.com")
phone = client.graphql.verification.phone_number("+61412345678")

# Network Engineering
asn = client.graphql.network_engineering.asn_info_full("AS13335",
    lambda q: q.basic_info().receiving_from())
```

Raw queries are also supported:

```python
data = client.graphql.ip_geolocation.query_raw("""
{
    ipData(ip: "1.1.1.1") {
        locality { city }
        country { name }
    }
}
""")
```

## Available APIs

| Client | Key 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_extended`, `get_receiving_from`, `get_transit_to`, `get_bgp_prefixes`, `get_networks_by_cidr`, `get_asn_rank_list`, `get_tor_exit_nodes` |
| `client.graphql.ip_geolocation` | `ip_data`, `country_info`, `user_agent`, `timezone_info`, `query_raw` |
| `client.graphql.reverse_geocoding` | `location_data`, `query_raw` |
| `client.graphql.verification` | `email_verification`, `phone_number`, `query_raw` |
| `client.graphql.network_engineering` | `asn_info_full`, `network_by_ip`, `query_raw` |

## Samples

```bash
python samples/ip_geolocation.py
python samples/reverse_geocoding.py
python samples/verification.py
python samples/network_engineering.py
python samples/graphql_sample.py
```

## License

MIT — see [LICENSE](LICENSE).
