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
• Quick Start
• API Reference
• Type Definitions
• Troubleshooting
• Changelog

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.

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

Troubleshooting

• 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.

Changelog

See CHANGELOG.md for release notes and upgrade guidance.

Contributing & Metadata

• Recommend adding repository and homepage fields to package.json for better discovery.
• Please open issues or PRs at the repository.

License

See LICENSE.

Support

• API docs: Docs
• Support: Contact
• Website: Home