IPGeolocation.io JavaScript SDK

Overview

Official JavaScript SDK for the IPGeolocation.io IP Geolocation API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data from one API. Includes ESM, CommonJS, and TypeScript declarations.

Works in Node.js 18+ and in other runtimes that already provide fetch.

Installation

npm install ip-geolocation-api-javascript-sdk

import { IpGeolocationClient } from "ip-geolocation-api-javascript-sdk";

const { IpGeolocationClient } = require("ip-geolocation-api-javascript-sdk");

Quick Start

import { IpGeolocationClient } from "ip-geolocation-api-javascript-sdk";

async function main() {
  const client = new IpGeolocationClient({
    apiKey: process.env.IPGEO_API_KEY,
  });

  try {
    const response = await client.lookupIpGeolocation({
      ip: "8.8.8.8",
    });

    console.log("IP:", response.data.ip); // "8.8.8.8"
    console.log("Country:", response.data.location?.countryName); // "United States"
    console.log("City:", response.data.location?.city);
    console.log("Timezone:", response.data.timeZone?.name);
    console.log("Credits charged:", response.metadata.creditsCharged);
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
});

You can pass plain objects to request methods. If you want validation before the request is sent, use LookupIpGeolocationRequest and BulkLookupIpGeolocationRequest.

At a Glance

Get Your API Key

To use most SDK features, create or access your IPGeolocation.io account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section
6. Pass it to new IpGeolocationClient({ apiKey: "YOUR_API_KEY" })

For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

What You Can Get From One API Call

Security and Risk Signals

Request include: ["security"] when you need the security object in the response.

Provider names, confidence scores, and last-seen dates appear when the API has that data.

Supported Endpoints

These two endpoints can return geolocation, company, ASN, timezone, network, currency, hostname, abuse, user-agent, and security data depending on your request and plan.

Authentication Modes

Plan Features and Limits

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

You can also pass a custom HttpTransport as the second constructor argument.

Available Methods

Request Options

Single Lookup Examples

The examples below assume you already have a configured client and are running inside an async function or an ESM module with top-level await:

import { IpGeolocationClient } from "ip-geolocation-api-javascript-sdk";

const client = new IpGeolocationClient({
  apiKey: process.env.IPGEO_API_KEY,
});

const response = await client.lookupIpGeolocation({});
console.log(response.data.ip);

const response = await client.lookupIpGeolocation({
  ip: "ipgeolocation.io",
});

console.log(response.data.ip);
console.log(response.data.domain); // "ipgeolocation.io"
console.log(response.data.location?.countryName);

const response = await client.lookupIpGeolocation({
  ip: "9.9.9.9",
  include: ["security", "abuse"],
});

console.log(response.data.security?.threatScore);
console.log(response.data.security?.isVpn);
console.log(response.data.abuse?.emails?.[0]);

const response = await client.lookupIpGeolocation({
  ip: "ipgeolocation.io",
  include: ["hostname", "liveHostname", "hostnameFallbackLive"],
});

console.log(response.data.hostname);

const response = await client.lookupIpGeolocation({
  ip: "8.8.8.8",
  include: ["user_agent"],
  userAgent:
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) " +
    "AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
});

console.log(response.data.userAgent?.name);
console.log(response.data.userAgent?.operatingSystem?.name);
console.log(response.data.userAgent?.device?.type);

const response = await client.lookupIpGeolocation({
  ip: "8.8.8.8",
  include: ["security"],
  fields: ["location.country_name", "security.threat_score", "security.is_vpn"],
  excludes: ["currency"],
});

console.log(response.data.location?.countryName);
console.log(response.data.security?.threatScore);
console.log(response.data.security?.isVpn);

import {
  IpGeolocationClient,
  LookupIpGeolocationRequest,
} from "ip-geolocation-api-javascript-sdk";

const client = new IpGeolocationClient({
  apiKey: process.env.IPGEO_API_KEY,
});

const request = new LookupIpGeolocationRequest({
  ip: "8.8.8.8",
  include: ["security"],
});

const response = await client.lookupIpGeolocation(request);
console.log(response.data.security?.isProxy);

const browserClient = new IpGeolocationClient({
  requestOrigin: "https://app.example.com",
});

const response = await browserClient.lookupIpGeolocation({
  ip: "8.8.8.8",
});

console.log(response.data.ip);

await browserClient.close();

Raw JSON and XML

Use raw methods when you want the original response body as a string.

import {
  IpGeolocationClient,
  ResponseFormat,
} from "ip-geolocation-api-javascript-sdk";

const client = new IpGeolocationClient({
  apiKey: process.env.IPGEO_API_KEY,
});

const rawJson = await client.lookupIpGeolocationRaw({
  ip: "8.8.8.8",
});

console.log(rawJson.data);

const rawXml = await client.lookupIpGeolocationRaw({
  ip: "8.8.8.8",
  output: ResponseFormat.XML,
});

console.log(rawXml.data);

Bulk Lookup Examples

Bulk lookup is a paid-plan feature and always requires apiKey.

const response = await client.bulkLookupIpGeolocation({
  ips: ["8.8.8.8", "1.1.1.1"],
});

for (const result of response.data) {
  if (result.success) {
    console.log(result.data.ip, result.data.location?.countryName); // "8.8.8.8", "United States"
  }
}

const response = await client.bulkLookupIpGeolocation({
  ips: ["8.8.8.8", "invalid-ip", "1.1.1.1"],
  include: ["security"],
});

for (const result of response.data) {
  if (result.success) {
    console.log(result.data.ip, result.data.security?.threatScore);
    continue;
  }

  console.error(result.error.message);
}

Response Metadata

Every SDK call returns an object with data and metadata.

metadata is an ApiResponseMetadata instance with:

It also provides:

• metadata.headerValues(name)
• metadata.firstHeaderValue(name)

Example:

const response = await client.lookupIpGeolocation({
  ip: "8.8.8.8",
});

console.log(response.metadata.statusCode);
console.log(response.metadata.durationMs);
console.log(response.metadata.firstHeaderValue("x-ratelimit-remaining"));

JSON Helpers

Use toJson() or toPrettyJson() when you want a stable JSON view of SDK objects.

import { toPrettyJson } from "ip-geolocation-api-javascript-sdk";

const response = await client.lookupIpGeolocation({
  ip: "8.8.8.8",
});

console.log(toPrettyJson(response.data));

Error Handling

All SDK errors extend IpGeolocationError.

Runtime and validation errors:

• ValidationError
• SerializationError
• TransportError
• RequestTimeoutError

API errors:

• ApiError
• BadRequestError
• UnauthorizedError
• NotFoundError
• MethodNotAllowedError
• PayloadTooLargeError
• UnsupportedMediaTypeError
• LockedError
• RateLimitError
• ClientClosedRequestError
• ServerError

ApiError and its subclasses expose:

• statusCode
• apiMessage

Example:

import {
  IpGeolocationClient,
  RateLimitError,
  UnauthorizedError,
} from "ip-geolocation-api-javascript-sdk";

const client = new IpGeolocationClient({
  apiKey: process.env.IPGEO_API_KEY,
});

try {
  const response = await client.lookupIpGeolocation({
    ip: "8.8.8.8",
  });
  console.log(response.data.location?.countryName);
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.error(error.apiMessage);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit reached");
  } else {
    throw error;
  }
} finally {
  await client.close();
}

Frequently Asked Questions

Related Packages

• TypeScript runtime SDK: ip-geolocation-api-sdk-typescript
• TypeScript types-only package: ip-geolocation-api-typescript-types

Links

• npm package
• GitHub repository
• API documentation
• Pricing
• Authentication
• Response formats