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

``bash
npm install ip-finder-client
`

`bash
yarn add ip-finder-client
`

`bash
pnpm add ip-finder-client
`

Quick Start

`typescript
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

`typescript
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

$3

Look up information for a single IP address.

`typescript
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 }
}
`

$3

Look up multiple IP addresses in parallel.

`typescript
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});
}
});
`

$3

Check if the API is healthy and reachable.

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

$3

Rate limit information is available after each request:

`typescript
await client.lookup('8.8.8.8');

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

Error Handling

`typescript
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});
}
}
`

$3

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

$3

| 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

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

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

Factory Function

Alternatively, use the factory function:

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

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

TypeScript Support

Full TypeScript support with exported types:

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

Requirements

- Node.js 18+ (uses native fetch`)

License

MIT