IPWho TypeScript SDK

A small, lightweight TypeScript SDK for the IPWho Geolocation API — get geolocation, timezone, connection and security information for IP addresses with typed responses.

Installation

Install via npm:

npm install @ipwho/ipwho

Or with yarn:

yarn add @ipwho/ipwho

Quick Start

import { IPWho } from '@ipwho/ipwho';

const client = new IPWho(process.env.IPWHO_API_KEY || 'your-api-key');

// Get caller's location (uses your IP by default)
const location = await client.getLocation();
console.log(location);

Example minimal response (normalized):

{
  "country": "United States",
  "countryCode": "US",
  "city": "San Francisco",
  "latitude": 37.7749,
  "longitude": -122.4194
}

API Reference

All methods accept an optional ip parameter. When omitted, the SDK queries the caller’s IP (/me). When provided, it queries /ip/{ip}.

• getLocation(ip?: string): Promise<GeoLocation | null> — Returns normalized geographical information.
• getTimezone(ip?: string): Promise<Timezone | null> — Returns timezone details, includes currentTime when available.
• getConnection(ip?: string): Promise<Connection | null> — ISP/ASN/org details.
• getSecurity(ip?: string): Promise<Security | null> — VPN/Tor/threat indicators.
• getMe(): Promise<IPWhoData> — Raw API payload for the caller’s IP.
• getIp(ip: string): Promise<IPWhoData> — Raw API payload for a specific IP.

Requirements

Requires a modern JavaScript runtime with fetch support (Node.js 18+ recommended).

Type definitions are shipped in the package — see the types field in package.json (dist/index.d.ts).

Type Definitions

See the distributed types in dist/index.d.ts for full typings. Example summary:

type GeoLocation = {
  continent: string;
  country: string;
  countryCode: string;
  city?: string | null;
  latitude?: number;
  longitude?: number;
};

Usage Examples

Basic usage (explicit IP):

const location = await client.getLocation('76.102.11.203');
console.log(location?.country, location?.city);

Handling errors:

try {
  const data = await client.getIp('invalid-ip');
  console.log(data);
} catch (err) {
  console.error('API or network error', err);
}

Using in a Node script (top-level await supported in modern Node):

# package.json: "type": "module"
node ./scripts/get-location.mjs

Browser usage note:

• The package works in modern browsers but requires an environment that provides fetch.
• Protect your API key; prefer server-side calls or proxy your requests.

Advanced: pass request options (timeout/retry) by wrapping or extending the client in your app, or use your own fetch implementation when more control is required.

Troubleshooting & Errors

• Missing API key: initialize with your API key or set X-API-Key header.
• Network errors: the SDK uses fetch/undici; network failures will throw and should be retried according to your app’s policy.
• API errors: when the API returns success: false the SDK surfaces an error.