Watch-IP

Use Watch-IP with Python

watch-ip-sdk (PyPI, v0.1.1) wraps GET /v1/geo in a dependency-free client built on Python's standard-library urllib. It doesn't cover IP lookup — the batch guide below calls that endpoint directly instead.

Install

Requires Python 3.9+. No third-party dependencies — the package uses urllib from the standard library.

pip

pip install watch-ip-sdk

Quick start

GET /v1/geo is designed to be called from a visitor's own browser. Calling it from Python means calling it from your own server instead, so the request won't carry the Origin header a browser sends automatically — pass origin explicitly, set to one of the key's allowed origins, or the API rejects the call with origin_not_allowed.

Python

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"])

Error handling and timeouts

Every failure raises a WatchIPError with a status and a stable code. get_geo() takes an optional timeout in seconds (default 10.0).

Python

from watch_ip import WatchIP, WatchIPError

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

try:
    geo = client.get_geo(timeout=5.0)
except WatchIPError as err:
    print(err.code, err.status, err)

IP lookup and batch lookup: use direct HTTP

This SDK has no method for GET /v1/lookup/{ip} or POST /v1/lookup — both server-to-server endpoints authenticated with a secret key rather than the publishable key this package wraps. Call them with urllib directly; the Python batch guide builds a complete chunked example on top of this.

Python

import json
import urllib.request

request = urllib.request.Request(
    "https://api.watch-ip.com/v1/lookup",
    data=json.dumps({"ips": ["203.0.113.1", "2001:db8::1"]}).encode(),
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    result = json.load(response)

Related pages