ipmax

Python client for the IP-Max GeoIP and IP intelligence API, with sync and async clients and fully typed responses.

Install

pip install ipmax

Requires Python 3.10 or newer.

Quickstart

from ipmax import IPMax

with IPMax("sg_live_...") as client:
    geo = client.geoip("8.8.8.8")
    print(geo.geo.city, geo.geo.country_code, geo.as_.name)

    intel = client.intelligence("8.8.8.8")
    print(intel.network_class.primary, intel.is_hosting)

The async client has the same methods:

import asyncio

from ipmax import AsyncIPMax


async def main() -> None:
    async with AsyncIPMax() as client:
        catalog = await client.catalog()
        account = await client.account()
        print(catalog.prices, account.wallets)


asyncio.run(main())

When no key is passed, the client reads IPMAX_API_KEY from the environment. catalog() works without a key.

Every lookup is billed and sends a fresh Idempotency-Key, which is reused when the request is retried. Pass your own with client.geoip(ip, idempotency_key="...") to make a lookup safe to repeat across processes.

Configuration

Cached lookups make no request and cost nothing. catalog() and account() are never cached. A lookup with an explicit idempotency key always goes to the API.

Error handling

import ipmax

try:
    client.geoip("8.8.8.8")
except ipmax.InsufficientBalanceError:
    ...
except ipmax.RateLimitError as error:
    print("retry in", error.retry_after)
except ipmax.ApiError as error:
    print(error.status, error.code, error.message, error.request_id)
except ipmax.ConnectionError:
    ...

ErrorCode holds the known values of error.code, such as ErrorCode.INSUFFICIENT_BALANCE. New codes may appear and are passed through as plain integers.

License

Apache-2.0