IP Flare

IP Geolocation API, our API enables you to effortlessly obtain precise geolocation data for any IP address through a single endpoint. Benefit from ultra-fast responses—typically between 50-200ms—and enjoy reliable performance with 99.9% uptime.

Visit our website: www.ipflare.io

Installation

Install the library using npm:

``bash
npm install ipflare
`

Getting Started

To use the library, you'll need an API key. You can obtain your API key from the IP Flare Dashboard.

Usage

$3

`typescript
import { IPFlare } from "ipflare";

// Initialize with your API key (required)
const geolocator = new IPFlare({
apiKey: "your-api-key",
});
`

$3

The API methods return a Result object with an ok property, eliminating the need for try-catch blocks:

#### Single IP Lookup

`typescript
// Result-based lookup - no try-catch needed
const result = await geolocator.lookup("178.238.11.6");

if (!result.ok) {
// Handle different error types
switch (result.error.type) {
case 'INVALID_IP_ADDRESS':
console.log('Invalid IP:', result.error.message);
break;
case 'RESERVED_IP_ADDRESS':
console.log('Reserved IP:', result.error.message);
break;
case 'UNAUTHORIZED':
console.log('API key issue:', result.error.message);
break;
case 'NO_API_KEY_PROVIDED':
console.log('No API key provided:', result.error.message);
break;
case 'QUOTA_EXCEEDED':
console.log('Quota exceeded:', result.error.message);
break;
case 'GEOLOCATION_NOT_FOUND':
console.log('Geolocation not found:', result.error.message);
break;
case 'INTERNAL_SERVER_ERROR':
console.log('Server error:', result.error.message);
break;
default:
console.log('Error:', result.error.message);
}
return;
}

// TypeScript knows result.data is IPGeolocationResponse
console.log('Location:', result.data.city, result.data.country_name);
`

#### Bulk IP Lookup

`typescript
// Result-based bulk lookup
const bulkResult = await geolocator.bulkLookup({
ips: ["178.238.11.6", "1.1.1.1"],
include: {
asn: true,
isp: true,
},
});

if (!bulkResult.ok) {
console.log('Bulk lookup failed:', bulkResult.error.message);
return;
}

// Process results
for (const item of bulkResult.data) {
if (item.status === 'success') {
console.log(${item.data.ip}: ${item.data.city}, ${item.data.country_name});
} else {
console.log(${item.ip}: Error - ${item.error_message});
}
}
`

#### Error Types

The Result-based API provides structured error types that match the actual API responses:

- INVALID_IP_ADDRESS - Invalid IP address format
- RESERVED_IP_ADDRESS - IP address is reserved (private/local)
- GEOLOCATION_NOT_FOUND - Geolocation data not available for this IP
- INTERNAL_SERVER_ERROR - Server-side error occurred
- INVALID_INPUT - Invalid input parameters
- UNAUTHORIZED - Invalid or missing API key
- QUOTA_EXCEEDED - API quota exceeded
- NO_API_KEY_PROVIDED - No API key was provided
- NETWORK_ERROR - Network connectivity issues
- VALIDATION_ERROR - Client-side input validation errors
- UNKNOWN_ERROR - Unexpected errors

$3

#### Lookup with Additional Fields

`typescript
const resultWithFields = await geolocator.lookup("178.238.11.6", {
include: {
asn: true,
isp: true,
},
});

if (resultWithFields.ok) {
console.log('ASN:', resultWithFields.data.asn);
console.log('ISP:', resultWithFields.data.isp);
} else {
console.error('Lookup failed:', resultWithFields.error.message);
}
`

#### Using Type Guards

`typescript
import { isSuccess, isError } from 'ipflare';

const result = await geolocator.lookup("8.8.8.8");

if (isSuccess(result)) {
// TypeScript knows this is a success result
console.log(IP ${result.data.ip} is in ${result.data.country_name});
} else if (isError(result)) {
// TypeScript knows this is an error result
console.log(Error: ${result.error.message});
}
``

Documentation

For more detailed information, please refer to our documentation:

- Get Geolocation
- Bulk Lookup
- Next.js Tutorial

Features

- Result-based API: No try-catch required, all methods return Result types
- Structured Error Handling: Comprehensive error types with detailed information
- Single IP Lookup: Fast geolocation lookup for individual IP addresses
- Bulk IP Lookup: Process up to 500 IPs in a single request
- IPv4 & IPv6 Support: Full support for both IPv4 and IPv6 addresses
- Optional Fields: ASN, ISP, and other additional data fields
- TypeScript Support: Full type definitions with type guards
- Input Validation: Client-side validation prevents invalid API calls
- Production Ready: Comprehensive testing and enterprise-grade reliability