BigDataCloud Python SDK

Official Python SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, Network Engineering — plus a GraphQL interface for all packages.

Installation

pip install bigdatacloud

API Key

Get a free API key at bigdatacloud.com/login. No credit card required.

Store your key in the BIGDATACLOUD_API_KEY environment variable:

export BIGDATACLOUD_API_KEY=your-key-here

Quick Start

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

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:

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:

# 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:

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

Available APIs

Samples

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.