IP Geolocation API in JavaScript: Node.js Examples and Recipes

export IPLOOKUPAPI_KEY="your_api_key"

// lib/iplookup.js: server-side only. Never import this file in browser code.
const BASE_URL = "https://api.iplookupapi.com/v1";

export class IplookupError extends Error {
  constructor(status, body) {
    super(body?.error?.message ?? body?.message ?? `HTTP ${status}`);
    this.status = status;
    this.code = body?.error?.code ?? null; // e.g. "quota_exceeded"
    this.body = body;
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(path, { params = {}, body, timeoutMs = 5000, retries = 3 } = {}) {
  const apiKey = process.env.IPLOOKUPAPI_KEY;
  if (!apiKey) throw new Error("IPLOOKUPAPI_KEY is not set");

  const url = new URL(`${BASE_URL}/${path}`);
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
  }

  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      method: body ? "POST" : "GET",
      headers: { apikey: apiKey, ...(body && { "Content-Type": "application/json" }) },
      body: body ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(timeoutMs), // throws a TimeoutError when exceeded
    });
    const data = await res.json().catch(() => null);
    if (res.ok) return data;

    // Retry rate limits and server errors; a used-up monthly quota will not recover.
    const retryable =
      res.status >= 500 || (res.status === 429 && data?.error?.code !== "quota_exceeded");
    if (!retryable || attempt >= retries) throw new IplookupError(res.status, data);
    await sleep(Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 250);
  }
}

// One IP. Leave ip undefined to look up the caller's own address.
export async function lookupIp(ip, params = {}) {
  const res = await call("info", { params: { ip, ...params } });
  return res.data;
}

// Any number of IPs: deduped, then sent in chunks of 1,000.
export async function batchLookup(ips, params = {}) {
  const unique = [...new Set(ips)];
  const result = { data: {}, errors: {} };
  for (let i = 0; i < unique.length; i += 1000) {
    const res = await call("batch", {
      params,
      body: { ips: unique.slice(i, i + 1000) },
      timeoutMs: 60_000,
    });
    Object.assign(result.data, res.data);
    Object.assign(result.errors, res.errors ?? {});
  }
  return result;
}

// Quota and plan. Free: does not count against your quota.
export function getStatus() {
  return call("status", { retries: 0 });
}

import { lookupIp } from "./lib/iplookup.js";

const geo = await lookupIp("8.8.8.8");

console.log(geo.location.country.alpha2); // country code
console.log(geo.location.city.name);      // city
console.log(geo.timezone.id);             // IANA time zone
console.log(geo.connection.isp, geo.connection.asn);

const me = await lookupIp();
console.log(me.ip, me.location.country.name);

const geo = await lookupIp("2001:4860:4860::8888", {
  fields: "ip,location.country.name,location.city.name,timezone.id",
  language: "de",
});

import { getStatus } from "./lib/iplookup.js";

const { quotas } = await getStatus();
console.log(quotas.month.used, "of", quotas.month.total, "used,", quotas.month.remaining, "left");

import { lookupIp, IplookupError } from "./lib/iplookup.js";

try {
  const geo = await lookupIp("8.8.8.8");
  console.log(geo.location.country.alpha2);
} catch (err) {
  if (err instanceof IplookupError && err.code === "quota_exceeded") {
    console.error("Monthly quota used up, resets at", err.body?.quota?.resets_at);
  } else {
    console.error("Lookup failed:", err.status ?? err.name, err.message);
  }
}

import { batchLookup } from "./lib/iplookup.js";

const ips = ["8.8.8.8", "80.110.0.1", "2001:4860:4860::8888", "not-an-ip"];
const { data, errors } = await batchLookup(ips, {
  fields: "ip,location.country.alpha2,connection.asn",
});

for (const [ip, info] of Object.entries(data)) {
  console.log(ip, info.location?.country?.alpha2 ?? "-", info.connection?.asn ?? "-");
}
console.log("Not looked up:", errors);

// lib/cache.js: a small in-memory cache with a time limit (TTL) and LRU eviction.
export class TtlCache {
  constructor({ max = 10_000, ttlMs = 6 * 60 * 60 * 1000 } = {}) {
    this.max = max;
    this.ttlMs = ttlMs;
    this.map = new Map(); // Map keeps insertion order: oldest entry first
  }

  get(key) {
    const hit = this.map.get(key);
    if (!hit) return undefined;
    this.map.delete(key);
    if (hit.expires < Date.now()) return undefined;
    this.map.set(key, hit); // move to the end: most recently used
    return hit.value;
  }

  set(key, value) {
    this.map.delete(key);
    this.map.set(key, { value, expires: Date.now() + this.ttlMs });
    if (this.map.size > this.max) this.map.delete(this.map.keys().next().value);
  }
}

// server.js
import express from "express";
import { lookupIp } from "./lib/iplookup.js";
import { TtlCache } from "./lib/cache.js";

const app = express();
app.set("trust proxy", ["loopback", "10.0.0.0/8"]); // your proxies: nginx on this host, load balancers

const cache = new TtlCache({ max: 10_000, ttlMs: 6 * 60 * 60 * 1000 }); // 6 hours

async function geolocate(req, res, next) {
  const ip = req.ip?.replace(/^::ffff:/, ""); // IPv4-mapped IPv6 to plain IPv4
  req.geo = null;
  if (!ip) return next();
  try {
    let geo = cache.get(ip);
    if (geo === undefined) {
      geo = await lookupIp(ip, {
        fields: "location.country.alpha2,location.city.name,timezone.id",
      });
      cache.set(ip, geo);
    }
    req.geo = geo;
  } catch (err) {
    // never fail the page because a lookup failed
    console.warn("IP lookup failed:", err.status ?? err.name, err.message);
  }
  next();
}

app.get("/", geolocate, (req, res) => {
  res.json({
    country: req.geo?.location?.country?.alpha2 ?? null,
    timezone: req.geo?.timezone?.id ?? null,
  });
});

app.listen(3000);

// app/api/geo/route.js
import { lookupIp } from "../../../lib/iplookup.js";

export async function GET(request) {
  // Vercel sets x-real-ip to the client's address; self-hosted, let your nginx set it
  // (proxy_set_header X-Real-IP $remote_addr) and keep Next.js reachable only through nginx.
  const ip = request.headers.get("x-real-ip");
  if (!ip) return Response.json({ error: "No client IP" }, { status: 400 });

  try {
    const geo = await lookupIp(ip, {
      fields: "location.country.alpha2,location.city.name,timezone.id",
    });
    return Response.json(geo, { headers: { "Cache-Control": "private, max-age=3600" } });
  } catch (err) {
    console.warn("IP lookup failed:", err.status ?? err.name, err.message);
    return Response.json({ error: "Lookup failed" }, { status: 502 });
  }
}

const geo = await fetch("/api/geo").then((res) => res.json());

// worker.js
import { lookupIp } from "./lib/iplookup.js";

export default {
  async fetch(request) {
    const ip = request.headers.get("CF-Connecting-IP");
    if (!ip) return Response.json({ error: "No client IP" }, { status: 400 });
    try {
      const geo = await lookupIp(ip, { fields: "location.country.alpha2,timezone.id" });
      return Response.json(geo);
    } catch (err) {
      return Response.json({ error: "Lookup failed" }, { status: 502 });
    }
  },
};

npx wrangler secret put IPLOOKUPAPI_KEY