TypeScript Library

The ipflare npm package offers a simple and efficient way to retrieve geolocation information for IP addresses using the IP Flare API. The library provides comprehensive TypeScript support, robust error handling, and advanced features for production applications.

GitHub NPM

Notice!

An API key is required to use this library. Obtain your API key from the API Keys page and include it in the X-API-Key header of your requests.

Features

Result-based Error Handling: All methods return a Result type with explicit success/failure states
IPv4 & IPv6 Support: Comprehensive validation for both IPv4 and IPv6 addresses
Type Safety: Full TypeScript support with type guards and discriminated unions
Input Validation: Client-side validation prevents invalid requests and provides immediate feedback
Structured Error Types: Specific error messages for different scenarios with structured error types
Bulk Operations: Process up to 500 IP addresses in a single request
Configurable: Custom timeout, base URL, and other configuration options
Production Ready: Comprehensive testing (96%+ coverage) and enterprise-grade reliability

Installation

1npm install ipflare

Quick Start

After installing the package, you can use it in your JavaScript or TypeScript projects to fetch geolocation data with comprehensive error handling and type safety. The library uses a Result-based approach that eliminates the need for try-catch blocks.

Initialize the Client

1// ipflare.ts
2
3import { IPFlare } from "ipflare";
4
5// Initialize with your API key (required)
6const geolocator = new IPFlare({
7  apiKey: 'YOUR_API_KEY',
8});

Optional settings:

timeout - milliseconds to wait for an answer (default 10000; 0 waits indefinitely)
retries - how many times to retry a single lookup that failed for a passing reason: a network error, a timeout, the API being briefly unavailable, or the rate limit (default 0). Bulk lookups are never retried, because they use your quota when the request arrives.
retryDelayMs - milliseconds before the first retry, doubling for each further one (default 250)

Both lookup and bulkLookup accept a signal (an AbortSignal) to cancel a request; a cancelled request returns an ABORTED error.

Examples

The library uses a Result-based API that eliminates try-catch blocks and provides structured error handling with explicit success/failure states.

Single IP Lookup

The following example demonstrates IP lookups with automatic validation for both IPv4 and IPv6 addresses and structured error information.

1const result = await geolocator.lookup("178.238.11.6");
2
3if (!result.ok) {
4  // Handle different error types
5  switch (result.error.type) {
6    case 'INVALID_IP_ADDRESS':
7      console.log('Invalid IP:', result.error.message);
8      break;
9    case 'UNAUTHORIZED':
10      console.log('API key issue:', result.error.message);
11      break;
12    case 'QUOTA_EXCEEDED':
13      console.log('Quota exceeded:', result.error.message);
14      break;
15    case 'GEOLOCATION_NOT_FOUND':
16      console.log('No geolocation data:', result.error.message);
17      break;
18    default:
19      console.log('Error:', result.error.message);
20  }
21  return;
22}
23
24// TypeScript knows result.data is IPGeolocationResponse
25console.log('Location:', result.data.city, result.data.country_name);
26console.log('Coordinates:', result.data.latitude, result.data.longitude);

Bulk IP Lookup

Bulk lookup for multiple IP addresses (up to 500 per request) with structured error handling. Results come back in the order of the addresses you asked for, one per address, so data[i] is the answer for ips[i]. An address that is not a valid IP address gets its own error result and is not sent, so it does not use your quota; the other addresses are looked up as usual.

1// Bulk lookup
2const bulkResult = await geolocator.bulkLookup({
3  ips: ["178.238.11.6", "1.1.1.1", "2001:4860:4860::8888"],
4  include: {
5    asn: true,
6    isp: true,
7  },
8});
9
10if (!bulkResult.ok) {
11  console.log('Bulk lookup failed:', bulkResult.error.message);
12  return;
13}
14
15// Process results
16for (const item of bulkResult.data) {
17  if (item.status === 'success') {
18    console.log(`${item.data.ip}: ${item.data.city}, ${item.data.country_name}`);
19    if (item.data.asn) console.log(`ASN: ${item.data.asn}`);
20    if (item.data.isp) console.log(`ISP: ${item.data.isp}`);
21  } else {
22    console.log(`${item.ip}: Error - ${item.error_message}`);
23  }
24}

Lookup with Additional Fields

To retrieve additional fields like ASN and ISP information, pass the include options. Visit the Geolocation page for more information about available fields.

1// Lookup with additional fields
2const result = await geolocator.lookup("178.238.11.6", {
3  include: {
4    asn: true,
5    isp: true,
6  },
7});
8
9if (!result.ok) {
10  console.log('Lookup failed:', result.error.message);
11  return;
12}
13
14console.log('IP:', result.data.ip);
15console.log('Location:', result.data.city, result.data.country_name);
16console.log('ASN:', result.data.asn);
17console.log('ISP:', result.data.isp);

Error Handling

The library provides comprehensive error handling with specific error types for different scenarios. No try-catch blocks are needed:

1import { IPFlare } from "ipflare";
2
3const geolocator = new IPFlare({ apiKey: 'your-api-key' });
4
5const result = await geolocator.lookup("8.8.8.8");
6
7if (!result.ok) {
8  // Handle specific error types
9  switch (result.error.type) {
10    case 'INVALID_IP_ADDRESS':
11      console.error('Please provide a valid IP address');
12      break;
13    case 'RESERVED_IP_ADDRESS':
14      console.error('IP address is reserved (private/local)');
15      break;
16    case 'UNAUTHORIZED':
17      console.error('Please check your API key');
18      break;
19    case 'QUOTA_EXCEEDED':
20      console.error('Usage quota exceeded, please upgrade your plan');
21      break;
22    case 'RATE_LIMIT_EXCEEDED':
23      console.error('Too many requests this minute, retry shortly');
24      break;
25    case 'GEOLOCATION_NOT_FOUND':
26      console.error('No geolocation data available for this IP');
27      break;
28    case 'INTERNAL_SERVER_ERROR':
29      console.error('Server error occurred, please try again');
30      break;
31    default:
32      console.error('Unexpected error:', result.error.message);
33  }
34  return;
35}
36
37// Success - TypeScript knows the exact type
38console.log('Success:', result.data);
39
40// Bulk lookup error handling
41const bulkResult = await geolocator.bulkLookup({
42  ips: ["8.8.8.8", "1.1.1.1"]
43});
44
45if (!bulkResult.ok) {
46  console.error('Bulk lookup failed:', bulkResult.error.message);
47  return;
48}
49
50console.log('Bulk results:', bulkResult.data);

Type Guards

The library provides type guard functions to safely work with results and discriminate between successful and error responses:

1import { 
2  IPFlare, 
3  isSuccess,
4  isError,
5  isIPGeolocationSuccess,
6  isIPGeolocationError
7} from "ipflare";
8
9const geolocator = new IPFlare({ apiKey: 'your-api-key' });
10
11// Result-based API with type guards
12const result = await geolocator.lookup("8.8.8.8");
13
14if (isSuccess(result)) {
15  // TypeScript knows this is a success response
16  console.log('Success:', result.data);
17  console.log('Country:', result.data.country_name);
18  console.log('City:', result.data.city);
19} else if (isError(result)) {
20  // TypeScript knows this is an error response
21  console.error('Error type:', result.error.type);
22  console.error('Error message:', result.error.message);
23}
24
25// Bulk lookup with type guards
26const bulkResult = await geolocator.bulkLookup({
27  ips: ["8.8.8.8", "1.1.1.1"]
28});
29
30if (isSuccess(bulkResult)) {
31  // Process each result in the bulk response
32  for (const item of bulkResult.data) {
33    if (isIPGeolocationSuccess(item)) {
34      console.log(`Success for ${item.ip}:`, item.data);
35    } else if (isIPGeolocationError(item)) {
36      console.error(`Error for ${item.ip}: ${item.error_message}`);
37    }
38  }
39}
40
41// Alternative approach using status property
42if (isSuccess(bulkResult)) {
43  bulkResult.data.forEach(result => {
44    switch (result.status) {
45      case "success":
46        console.log("Success:", result.data);
47        break;
48      case "error":
49        console.error("Error:", result.error_message);
50        break;
51    }
52  });
53}

TypeScript Types

The ipflare library provides comprehensive TypeScript types for all operations:

1import {
2  IPFlare,
3  type BulkLookupOptions,
4  type BulkLookupResponse,
5  type IPGeolocationError,
6  type IPGeolocationOptions,
7  type IPGeolocationResponse,
8  type IPGeolocationSuccess,
9  type LookupOptions,
10  type Result,
11  type ErrorType,
12  // Type guard functions
13  isSuccess,
14  isError,
15  isIPGeolocationError,
16  isIPGeolocationSuccess,
17} from "ipflare";

Advanced Features

Input Validation

The library performs comprehensive client-side validation to prevent invalid requests and provide immediate feedback:

1// These will return error results immediately (no API call made)
2const invalidIPResult = await geolocator.lookup("invalid-ip");
3if (!invalidIPResult.ok) {
4  console.error(invalidIPResult.error.message); // "Invalid IP address format: invalid-ip"
5}
6
7const emptyBulkResult = await geolocator.bulkLookup({ ips: [] });
8if (!emptyBulkResult.ok) {
9  console.error(emptyBulkResult.error.message); // "At least one IP address is required"
10}
11
12const tooManyIPsResult = await geolocator.bulkLookup({ 
13  ips: new Array(501).fill("1.1.1.1") 
14});
15if (!tooManyIPsResult.ok) {
16  console.error(tooManyIPsResult.error.message); // "Maximum of 500 IPs per request allowed"
17}

Error Reference

Error Types

The library 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
RATE_LIMIT_EXCEEDED - Too many requests a minute from your address; retry shortly (your quota is not spent)
NETWORK_ERROR - The API could not be reached (the message says why)
TIMEOUT - The API did not answer within timeout
ABORTED - The request was cancelled through its signal
SERVICE_UNAVAILABLE - The API was briefly unavailable (502, 503 or 504); try again shortly
UNKNOWN_ERROR - Unexpected errors

Result Type Structure

All methods return a Result type with the following structure:

1// Success result
2type SuccessResult<T> = {
3  ok: true;
4  data: T;
5}
6
7// Error result
8type ErrorResult = {
9  ok: false;
10  error: {
11    type: ErrorType;
12    message: string;
13    details?: unknown;
14  };
15}
16
17// Combined result type
18type Result<T> = SuccessResult<T> | ErrorResult;

Common Error Messages

The library provides specific error messages for different scenarios:

"API key is required" - No API key provided
"API key must be a string" - Invalid API key type
"API key cannot be empty" - Empty API key
"IP address is required" - No IP address provided
"IP address must be a string" - Invalid IP type
"Invalid IP address format: [ip]" - Invalid IP format
"IPs must be an array" - Invalid bulk IPs type
"At least one IP address is required" - Empty IP array
"Maximum of 500 IPs per request allowed" - Too many IPs
"Invalid API key" - HTTP 401 response, when the API sends no message of its own
"Quota exceeded" - HTTP 429 response, when the API sends no message of its own

Something missing?

You can share your thoughts, request new features, report bugs, or ask questions by emailing hello@ipflare.io.