@digitload/watch-ip-sdk

Official JavaScript/TypeScript SDK for the Watch-IP visitor geolocation API.

Watch-IP looks up the geolocation of whoever is currently loading your page — call it 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.

Install

npm install @digitload/watch-ip-sdk

Usage

import { WatchIP } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");
const geo = await client.getGeo();

console.log(geo.country, geo.city, geo.timezone);

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

import { getGeo } from "@digitload/watch-ip-sdk";

const geo = await getGeo("wip_pub_xxxxxxxx");

Error handling

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

import { WatchIP, WatchIPError } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");

try {
  const geo = await client.getGeo();
} catch (err) {
  if (err instanceof WatchIPError) {
    console.error(err.code, err.status, err.message);
    // e.g. "origin_not_allowed" 403 "This origin is not authorized for this API key."
  }
}

Aborting a request

const controller = new AbortController();
const geo = await client.getGeo({ signal: controller.signal });

Requirements

Node.js 18+ or any modern browser (both have global fetch). No runtime dependencies.

License

MIT