ip-details-harshil 🚀

Fast, lightweight, and resilient IP geolocation & address lookup for Node.js with built-in automatic backup API failover.

✨ Features

• 📍 Detailed IP Geolocation: Get city, state/region, country, ISO country code, postal code, latitude, longitude, timezone, and ISP/organization.
• 🛡️ Built-in Failover / Backup API: If the primary geolocation API fails (timeout, rate limit, HTTP error), ip-details-harshil automatically switches to backup APIs seamlessly.
• ⚡ Zero External Dependencies: Powered by native fetch and AbortController (Node 18+).
• 📦 Dual Module Support: Works out of the box with ES Modules (import) and CommonJS (require).
• 🔷 TypeScript Native: Includes full TypeScript declarations (.d.ts).
• ⚙️ Fully Configurable: Custom timeouts, custom provider order, debug mode, and custom provider adapters.

👤 Author

Harshil Patel

📦 Installation

npm install ip-details-harshil

🚀 Quick Start

1. Fetch Caller's Public IP & Location Details

import { getIpDetails } from 'ip-details-harshil';

// Get geolocation for your own public IP address
const details = await getIpDetails();

console.log(details);
/*
{
  ip: '2405:f600:34:91be:...',
  city: 'Ahmedabad',
  state: 'Gujarat',
  country: 'India',
  countryCode: 'IN',
  postalCode: '380001',
  latitude: 23.0215,
  longitude: 72.5800,
  timezone: 'Asia/Kolkata',
  isp: 'Ishan s Network',
  sourceApi: 'ipwhois'
}
*/

2. Fetch Details for a Specific IP Address

import { getIpDetails } from 'ip-details-harshil';

const details = await getIpDetails('8.8.8.8');

console.log(`IP: ${details.ip}`);
console.log(`Location: ${details.city}, ${details.state}, ${details.country}`);
console.log(`Postal Code: ${details.postalCode}`);
console.log(`Provided by: ${details.sourceApi}`);

3. Quick Helper: Get Only Public IP

import { getPublicIp } from 'ip-details-harshil';

const myIp = await getPublicIp();
console.log(`Your IP is: ${myIp}`);

4. CommonJS Usage (require)

const { getIpDetails, getPublicIp } = require('ip-details-harshil');

getIpDetails('1.1.1.1').then(details => {
  console.log(details.country, details.sourceApi);
});

🔄 How the Backup API Fallback Works

ip-details-harshil maintains a default chain of high-availability geolocation providers:

1. ipwhois (https://ipwho.is/) — Primary API
2. freeipapi (https://freeipapi.com/api/json/) — Backup API 1
3. ipapi (https://ipapi.co/json/) — Backup API 2

If the primary API fails (e.g. timeout, network down, 5xx server error), ip-details-harshil silently catches the error and immediately queries the next backup API in the list.

Enabling Failover Logs (Debug Mode)

const details = await getIpDetails('8.8.8.8', {
  debug: true
});

Console output if Primary API fails:

[ip-details-harshil] Provider "ipwhois" failed: 503 Service Unavailable. Trying backup provider...

⚙️ Advanced Configuration Options

You can pass an optional options object to getIpDetails(ip, options):

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | timeout | number | 5000 | Request timeout in milliseconds per provider | | providers | (string \| ProviderFunction)[] | ['ipwhois', 'freeipapi', 'ipapi'] | Array of provider names or custom provider functions | | debug | boolean | false | Log warnings when a provider fails and switches to backup |

Customizing Provider Fallback Order & Timeout

const details = await getIpDetails('8.8.8.8', {
  timeout: 3000, // 3 seconds timeout per API
  providers: ['freeipapi', 'ipwhois'], // Custom priority order
  debug: true
});

Adding Custom API Providers

You can define your own custom geolocation provider function:

const customProvider = {
  name: 'my-custom-geo-api',
  async fetchDetails(ip, timeoutMs) {
    // Custom fetch logic
    return {
      ip: ip,
      city: 'Custom City',
      state: 'Custom State',
      country: 'Custom Country',
      countryCode: 'CC',
      postalCode: '123456',
      latitude: 0,
      longitude: 0,
      timezone: 'UTC',
      isp: 'Custom ISP',
      sourceApi: 'my-custom-geo-api'
    };
  }
};

const details = await getIpDetails('8.8.8.8', {
  providers: [customProvider, 'ipwhois']
});

📋 Response Schema Reference (IpDetails)

| Field | Type | Description | | :--- | :--- | :--- | | ip | string | The target IPv4 or IPv6 address | | city | string \| null | City name | | state | string \| null | State or region name | | country | string \| null | Country name | | countryCode | string \| null | ISO 2-letter country code (e.g. US, IN) | | postalCode | string \| null | Postal or ZIP code | | latitude | number \| null | Latitude coordinate | | longitude | number \| null | Longitude coordinate | | timezone | string \| null | Timezone identifier (e.g. America/New_York) | | isp | string \| null | ISP or Organization name | | sourceApi | string | Name of the API that successfully provided the data |

📜 License

MIT © Harshil Patel