ipatlas 0.1.0

Official IP-Atlas API client — IP geolocation, ASN, VPN detection

ipatlas

Official Python client for the IP-Atlas API — IP geolocation, ASN lookup, VPN/proxy/Tor detection, batch lookup, and account management.

Install

pip install ipatlas

Requires Python 3.8+. Depends on requests.

Quickstart

Without an API key (free anonymous tier)

from ipatlas import IPAtlas

client = IPAtlas()

# Look up your own IP
me = client.lookup_self()
print(me["country"], me["org"])

# Look up a specific IP (anonymous is limited to 60 req/min)
result = client.lookup("8.8.8.8")
print(result["asn"], result["is_datacenter"])

With an API key

from ipatlas import IPAtlas

client = IPAtlas(api_key="ipa_live_...")

result = client.lookup("1.1.1.1")
print(result)

Batch lookup (up to 100 IPs)

from ipatlas import IPAtlas

client = IPAtlas(api_key="ipa_live_...")

batch = client.lookup_batch(["8.8.8.8", "1.1.1.1", "not-an-ip"])
for item in batch["results"]:
    if "error" in item:
        print(f"{item['ip']}: {item['error']}")
    else:
        print(item["ip"], item.get("country"), item.get("org"))

Responses come back in the same order as the input list. Each element is either a successful lookup dict or a per-IP error dict {"ip": ..., "error": "..."}. Request-level failures (auth, quota) raise IPAtlasError.

Account management

info = client.account()
print(f"Plan: {info['plan']}, used {info['monthly_used']}/{info['monthly_limit']} this month")

# Rotate the key (old one is revoked, new one returned once)
new = client.rotate_key()
print(new["api_key"])

Error handling

from ipatlas import IPAtlas, IPAtlasError

client = IPAtlas(api_key="ipa_live_...")

try:
    result = client.lookup("not-an-ip")
except IPAtlasError as e:
    print(f"API error {e.status_code}: {e.body}")

API

IPAtlas(api_key=None, base_url='https://api.ip-atlas.io')

Parameter	Type	Default	Description
api_key	str	None	API key sent as X-API-Key header
base_url	str	https://api.ip-atlas.io	Override the API base URL

client.lookup(ip) -> dict

Returns geolocation + ASN + threat data for the given IPv4 or IPv6 address.

client.lookup_self() -> dict

Returns data for the caller's own IP address.

client.lookup_batch(ips) -> dict

Looks up up to 100 IPs in a single request. Returns {"results": [...]} where each element is in the same order as the input list.

client.account() -> dict

Returns the plan, key prefix, daily/monthly usage, and Stripe linkage for the bound API key.

client.rotate_key() -> dict

Revokes the current key and issues a replacement with the same plan. The new plaintext key is only returned once.

Links

• Documentation
• Get an API key
• GitHub