Lightweight SDK for IP geolocation, ASN lookup, and network information
npm install ip-finder-clientA lightweight, zero-dependency Node.js SDK for IP geolocation, ASN lookup, and network information.
Get your free API key at ipwhere.site
``bash`
npm install ip-finder-client
`bash`
yarn add ip-finder-client
`bash`
pnpm add ip-finder-client
`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"
`
`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,
});
`
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 }
}
`
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});${result.ip}: ${result.location?.country}
} else {
console.log();`
}
});
Check if the API is healthy and reachable.
`typescript`
const isHealthy = await client.healthCheck();
console.log(isHealthy ? 'API is up!' : 'API is down');
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 }
`
`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});Status Code: ${error.statusCode}
console.error();Error Code: ${error.code}
console.error();`
}
}
| Code | Description |
|------|-------------|
| TIMEOUT | Request timed out |NETWORK_ERROR
| | Network connectivity issue |BATCH_ERROR
| | Error during batch lookup |
| 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 |
`javascript
const { IPInsight } = require('ip-finder-client');
const client = new IPInsight({ apiKey: 'your-api-key' });
`
Alternatively, use the factory function:
`typescript
import { createClient } from 'ip-finder-client';
const client = createClient({
apiKey: 'your-api-key'
});
`
Full TypeScript support with exported types:
`typescript`
import type {
IPFinderConfig,
IPLookupResult,
Location,
ISP,
Network,
RateLimitInfo
} from 'ip-finder-client';
- Node.js 18+ (uses native fetch`)
MIT