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:

Method	Endpoint	Product page
lookup(ip=None)	GET /api/v1/ip[/{ip}]	IP geolocation
lookup_batch(ips)	POST /api/v1/ip/batch (≤100 IPs)	Bulk IP lookup
email_info(email)	GET /api/v1/email/{email}	Email validation
validate_email(email)	GET /api/v1/email/advanced/{email}	Advanced email validation
validate_email_batch(emails)	POST /api/v1/email/advanced/batch (≤100)	Email list cleaning
risk_score(ip=None)	GET /api/v1/risk-score[/{ip}]	Risk score
email_risk_score(email)	GET /api/v1/risk-score/email/{email}	Fraud detection
ip_reputation(ip)	GET /api/v1/ip-reputation/{ip}	IP reputation
tor_check(ip)	GET /api/v1/tor/{ip}	Tor detection
asn(ip)	GET /api/v1/asn/{ip}	ASN lookup
whois(domain)	GET /api/v1/dns/whois/{domain}	WHOIS lookup
reverse_dns(ip)	GET /api/v1/dns/reverse/{ip}	Reverse DNS
forward_dns(hostname)	GET /api/v1/dns/forward/{hostname}	—
mx_records(domain)	GET /api/v1/dns/mx/{domain}	MX record lookup
domain_age(domain)	GET /api/v1/domain/age/{domain}	Domain age checker
domain_age_batch(domains)	POST /api/v1/domain/age/batch	Domain age checker
rate_limit()	GET /api/v1/ratelimit	—
usage_summary()	GET /api/v1/usage/summary	—

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

• Full tutorial: https://ip-api.io/docs/sdk/python
• 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.