Watch-IP

Use Watch-IP with JavaScript and TypeScript

@digitload/watch-ip-sdk (npm, v0.1.1) wraps GET /v1/geo in a small client with TypeScript types for every response field and no runtime dependencies.

Install

Requires Node.js 18+ or any modern browser — both provide the global fetch this package builds on.

npm

npm install @digitload/watch-ip-sdk

Quick start

Construct a client with your publishable key and call getGeo(). The returned GeoResponse is fully typed; every field except ip and isEUCountry is nullable, so check a field before you render it.

TypeScript

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);

Error handling and timeouts

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. There's no built-in timeout; pass an AbortController's signal to cancel a slow request yourself.

TypeScript

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

const client = new WatchIP("wip_pub_xxxxxxxx");
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  const geo = await client.getGeo({ signal: controller.signal });
} catch (err) {
  if (err instanceof WatchIPError) {
    console.error(err.code, err.status, err.message);
  }
}

Optional fields

Pass include: ["hostname"] to add a reverse-DNS lookup for the connecting IP. It's opt-in because it adds an extra network hop, so only request it if you use the field.

TypeScript

const geo = await client.getGeo({ include: ["hostname"] });

What this SDK doesn't cover

This package only calls GET /v1/geo. It has no methods for IP lookup, email validation, or risk checks — those are server-to-server endpoints authenticated with a secret key, not the publishable key this SDK is built around. Call them directly over HTTP; see the IP lookup reference and authentication guide.

Related pages