ip-finder-client

A lightweight, zero-dependency Node.js SDK for IP geolocation, ASN lookup, and network information.

Get Your API Key

Get your free API key at ipwhere.site

Installation

npm install ip-finder-client

yarn add ip-finder-client

pnpm add ip-finder-client

Quick Start

import { IPInsight } from 'ip-finder-client';

const client = new IPInsight({
  apiKey: 'your-api-key'
});

// Look up an IP address
const result = await client.lookup('8.8.8.8');

console.log(result.location?.country);  // "US"
console.log(result.location?.city);     // "Mountain View"
console.log(result.isp?.organization);  // "GOOGLE"
console.log(result.isp?.asn);           // "AS15169"

Configuration

const client = new IPInsight({
  // Required: Your API key
  apiKey: 'your-api-key',

  // Optional: Request timeout in ms (default: 10000)
  timeout: 5000,

  // Optional: Number of retries for failed requests (default: 2)
  retries: 3,
});

API Reference

lookup(ip: string): Promise<IPLookupResult>

Look up information for a single IP address.

const result = await client.lookup('8.8.8.8');

// Result structure:
{
  ip: '8.8.8.8',
  ipDetails: { version: 4, decimal: '134744072', hex: '08080808' },
  location: {
    city: 'Mountain View',
    region: 'California',
    country: 'US',
    timezone: 'America/Los_Angeles',
    coordinates: { latitude: 37.422, longitude: -122.085 },
    maps: { search: '...', place: '...', directions: '...' }
  },
  isp: {
    organization: 'GOOGLE',
    asn: 'AS15169',
    domain: 'google.com',
    connectionType: 'Cable/DSL'
  },
  network: {
    cidr: '8.8.8.0/24',
    rir: 'ARIN',
    status: 'allocated'
  },
  cloud: { isCloud: false }
}

lookupBatch(ips: string[]): Promise<(IPLookupResult | IPInsightError)[]>

Look up multiple IP addresses in parallel.

const results = await client.lookupBatch(['8.8.8.8', '1.1.1.1', '9.9.9.9']);

results.forEach(result => {
  if (result instanceof IPInsightError) {
    console.error(`Error: ${result.message}`);
  } else {
    console.log(`${result.ip}: ${result.location?.country}`);
  }
});

healthCheck(): Promise<boolean>

Check if the API is healthy and reachable.

const isHealthy = await client.healthCheck();
console.log(isHealthy ? 'API is up!' : 'API is down');

Rate Limiting

Rate limit information is available after each request:

await client.lookup('8.8.8.8');

console.log(client.rateLimit);
// { limit: 1000, remaining: 999, reset: 1703980800 }

Error Handling

import { IPInsight, IPInsightError } from 'ip-finder-client';

try {
  const result = await client.lookup('invalid-ip');
} catch (error) {
  if (error instanceof IPInsightError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
    console.error(`Error Code: ${error.code}`);
  }
}

Error Codes

| Code | Description | |------|-------------| | TIMEOUT | Request timed out | | NETWORK_ERROR | Network connectivity issue | | BATCH_ERROR | Error during batch lookup |

HTTP Status Codes

| Status | Description | |--------|-------------| | 400 | Invalid IP address format | | 401 | Invalid or missing API key | | 404 | IP not found in database | | 429 | Rate limit exceeded | | 500 | Server error |

CommonJS Usage

const { IPInsight } = require('ip-finder-client');

const client = new IPInsight({ apiKey: 'your-api-key' });

Factory Function

Alternatively, use the factory function:

import { createClient } from 'ip-finder-client';

const client = createClient({
  apiKey: 'your-api-key'
});

TypeScript Support

Full TypeScript support with exported types:

import type {
  IPFinderConfig,
  IPLookupResult,
  Location,
  ISP,
  Network,
  RateLimitInfo
} from 'ip-finder-client';

Requirements

• Node.js 18+ (uses native fetch)

License

MIT