Client IP and Geolocation Extractor

client-ip-geolocation is a lightweight NPM package that extracts the client's IP address from an HTTP request object and fetches its geolocation details using an external API.

Features

• Extracts the client’s IP address from common headers and socket information.
• Supports various proxy and CDN headers like x-forwarded-for, cf-connecting-ip, and more.
• Provides detailed geolocation information such as country, region, city, latitude, longitude, ISP, timezone, and zip code using a geolocation API.

Installation

Install the package via NPM:

npm install client-ip-geolocation

Usage

Basic Example

import { createServer, IncomingMessage } from "http";
import { getClientIp, getClientIpAndLocation } from "client-ip-geolocation";

const server = createServer(async (req: IncomingMessage, res) => {
  const clientIp = getClientIp(req);
  console.log("Client IP:", clientIp);

  const geoLocation = await getClientIpAndLocation(req);
  if (geoLocation) {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(geoLocation));
  } else {
    res.writeHead(500, { "Content-Type": "text/plain" });
    res.end("Unable to fetch geolocation");
  }
});

server.listen(3000, () => {
  console.log("Server is running on http://localhost:3000");
});

Methods

getClientIp(req: any): string | null | undefined

Extracts the client’s IP address from the HTTP request.

• Parameters:

  • req: The any object from an HTTP request.

• Returns:

  • The client’s IP address as a string or null | undefined if not found.

getClientIpAndLocation(req: any): Promise<GeoLocation | null>

Fetches the client’s geolocation details using their IP address.

• Parameters

  • req: The `any object from an HTTP request.

• Returns:

  • A promise resolving to a GeoLocation object or null | undefine if geolocation fails.

GeoLocation Object Structure

interface GeoLocation {
  ip: string;
  country: string;
  countryCode: string;
  regionCode: string;
  regionName: string;
  city: string;
  geolocation: [
    {
      lat: number;
      lon: number;
    }
  ];
  isp: string;
  timezone: string;
  zip: string;
}

Example Output

When using the getClientIpAndLocation method, you may get a result like this:

{
  "ip": "203.0.113.195",
  "country": "United States",
  "countryCode": "US",
  "regionCode": "CA",
  "regionName": "California",
  "city": "San Francisco",
  "geolocation": [
    {
      "lat": 37.7749,
      "lon": -122.4194
    }
  ],
  "isp": "Comcast Cable",
  "timezone": "America/Los_Angeles",
  "zip": "94103"
}

Requirements

• Node.js >=14.x
• A network connection to call the geolocation API.

Notes

• The package uses the ip-api service by default to fetch geolocation. You can replace this API with your preferred geolocation provider if required.
• Ensure you handle API rate limits and errors gracefully in production environments.

License

• This package is open-source and available under the MIT License.

Contributing

• Contributions are welcome! If you’d like to add features or improve the package, feel free to submit a pull request.

Git Repository

https://github.com/vicky705/client-ip-geolocation.git

Issues

• If you encounter any issues, please open an issue on the GitHub repository.

Author

Vicky705 (Vicky Kumar)

https://github.com/vicky705