ip-api-io — Official Python client for ip-api.io

The official Python client for the ip-api.io IP intelligence platform. One client covers IP geolocation, email validation and verification (syntax, MX, SMTP deliverability), fraud detection and risk scoring, VPN/proxy/Tor detection, disposable email detection, ASN lookup, WHOIS, reverse DNS, MX records and domain age.

Zero dependencies — pure standard library.

Install

pip install ip-api-io

Quickstart

from ipapi_io import IpApiClient

client = IpApiClient(api_key="YOUR_API_KEY")  # free key at https://ip-api.io

# Where is this IP, and is it risky?
info = client.lookup("8.8.8.8")
print(info["location"]["country"])            # "United States"
print(info["suspicious_factors"]["is_vpn"])   # False

risk = client.risk_score("8.8.8.8")
print(risk["score"], risk["risk_level"])      # 0 "low"

email = client.validate_email("user@example.com")
print(email["reachable"], email["disposable"]) # "yes" False

An API key is required — the API rejects keyless requests with 401. Sign up at ip-api.io for a free key.

Documentation

Each guide documents the methods for one capability, with runnable examples and a link to the matching ip-api.io product page:

• IP geolocation & bulk lookup — lookup, lookup_batch
• Email validation & verification — email_info, validate_email, validate_email_batch
• Fraud detection & risk scoring — risk_score, email_risk_score, ip_reputation
• VPN, proxy & Tor detection — tor_check, suspicious_factors
• ASN & DNS lookups — asn, whois, reverse_dns, forward_dns, mx_records
• Domain age checker — domain_age, domain_age_batch
• Errors, rate limits & usage — exception types, rate_limit, usage_summary

Methods

Every method maps to one ip-api.io endpoint and its product page:

All methods return parsed JSON as plain dicts. ipapi_io.types ships TypedDict definitions for editor autocompletion.

Error handling

The client raises typed exceptions and never retries — on 429, RateLimitError.reset tells you when your quota renews:

from ipapi_io import IpApiClient, RateLimitError, AuthenticationError

client = IpApiClient(api_key="YOUR_API_KEY")
try:
    client.lookup("8.8.8.8")
except RateLimitError as e:
    print(f"limit={e.limit} remaining={e.remaining} resets_at={e.reset}")
except AuthenticationError:
    print("invalid API key")

See docs/error-handling.md for the full exception taxonomy.

Links

• Website: https://ip-api.io
• API reference: https://ip-api.io/api-docs.html
• OpenAPI spec: https://ip-api.io/openapi.json
• Get a free API key: https://ip-api.io

ip-api-io is the official client for ip-api.io. It is not affiliated with ip-api.com or ipapi.com.