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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file watch_ip_sdk-0.1.1.tar.gz.
File metadata
- Download URL: watch_ip_sdk-0.1.1.tar.gz
- Upload date:
- Size: 6.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b3edf7e206c6ee34a5f006b36374c91de47ce5e4f072206d89e1312ce9c811a9
|
|
| MD5 |
955d3436c3d250af7ba617230c607263
|
|
| BLAKE2b-256 |
251a402d99154725724c0393c8b0bd1f438048e9b9ce8d7f0e85a51e3246d817
|
Provenance
The following attestation bundles were made for watch_ip_sdk-0.1.1.tar.gz:
Publisher:
sdk-python-publish.yml on Digitload/watch-ip
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
watch_ip_sdk-0.1.1.tar.gz -
Subject digest:
b3edf7e206c6ee34a5f006b36374c91de47ce5e4f072206d89e1312ce9c811a9 - Sigstore transparency entry: 2732103389
- Sigstore integration time:
-
Permalink:
Digitload/watch-ip@25682888d149b458a2284fcec4c9e46622ad0996 -
Branch / Tag:
refs/tags/sdk-python-v0.1.1 - Owner: https://github.com/Digitload
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
sdk-python-publish.yml@25682888d149b458a2284fcec4c9e46622ad0996 -
Trigger Event:
push
-
Statement type:
File details
Details for the file watch_ip_sdk-0.1.1-py3-none-any.whl.
File metadata
- Download URL: watch_ip_sdk-0.1.1-py3-none-any.whl
- Upload date:
- Size: 5.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fccc40ba954c294204cebdfa05c7b07f1b71d298c7e8b2da60d408ec8637203f
|
|
| MD5 |
ffb97dbfb4156cec6efea5b54b45087b
|
|
| BLAKE2b-256 |
0b8048e5f199f32a930b8883b549f281b2879bef4cb6bb0ed88c41168ce1b4bb
|
Provenance
The following attestation bundles were made for watch_ip_sdk-0.1.1-py3-none-any.whl:
Publisher:
sdk-python-publish.yml on Digitload/watch-ip
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
watch_ip_sdk-0.1.1-py3-none-any.whl -
Subject digest:
fccc40ba954c294204cebdfa05c7b07f1b71d298c7e8b2da60d408ec8637203f - Sigstore transparency entry: 2732103998
- Sigstore integration time:
-
Permalink:
Digitload/watch-ip@25682888d149b458a2284fcec4c9e46622ad0996 -
Branch / Tag:
refs/tags/sdk-python-v0.1.1 - Owner: https://github.com/Digitload
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
sdk-python-publish.yml@25682888d149b458a2284fcec4c9e46622ad0996 -
Trigger Event:
push
-
Statement type:
