watch-ip-sdk

Official Python SDK for the Watch-IP visitor geolocation API.

Watch-IP looks up the geolocation of whoever is currently loading your page — it's designed to be called directly from the visitor's own browser with a publishable, origin-locked API key. There is no server-to-server or arbitrary-IP lookup mode; see the docs for why.

Calling it from Python therefore means calling it from your own server rather than a visitor's browser. That's a legitimate way to use this SDK for testing or internal tooling, but the request won't carry the Origin header a browser fetch sends automatically — and origin-locking means the API will reject it with origin_not_allowed unless you set origin= to one of the key's allowed origins yourself.

Install

pip install watch-ip-sdk

Usage

from watch_ip import WatchIP

client = WatchIP("wip_pub_xxxxxxxx", origin="https://example.com")
geo = client.get_geo()

print(geo["country"], geo["city"], geo["timezone"])

Or, for a one-off call without holding onto a client instance:

from watch_ip import get_geo

geo = get_geo("wip_pub_xxxxxxxx", origin="https://example.com")

Error handling

Every failure — a rejected request (invalid key, disallowed origin, rate limit) or a network error — raises a WatchIPError with a status and a stable code:

from watch_ip import WatchIP, WatchIPError

client = WatchIP("wip_pub_xxxxxxxx", origin="https://example.com")

try:
    geo = client.get_geo()
except WatchIPError as err:
    print(err.code, err.status, err)
    # e.g. "origin_not_allowed" 403 "This origin is not authorized for this API key."

Optional fields and timeouts

geo = client.get_geo(include=["hostname"], timeout=5.0)

Requirements

Python 3.9+. No runtime dependencies (uses urllib from the standard library).

License

MIT