Metadata-Version: 2.5
Name: watch-ip-sdk
Version: 0.1.0
Summary: Official Python SDK for the Watch-IP visitor geolocation API.
Project-URL: Homepage, https://watch-ip.com
Project-URL: Documentation, https://watch-ip.com/docs
Project-URL: Repository, https://github.com/Digitload/watch-ip
Project-URL: Issues, https://github.com/Digitload/watch-ip/issues
Author: Digitload
License-Expression: MIT
License-File: LICENSE
Keywords: cloudflare,geoip,geolocation,ip,watch-ip
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# watch-ip-sdk

Official Python SDK for the [Watch-IP](https://watch-ip.com) 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](https://watch-ip.com/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

```sh
pip install watch-ip-sdk
```

## Usage

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

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

```python
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`:

```python
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

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

## Requirements

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

## License

MIT
