geoip-flag

GEO IP FLAG

A lightweight package to retrieve detailed geolocation data from an IP address, including country code, flag emoji, city, region, timezone, currency, and more. Supports automatic IP detection for client-side and server-side applications.

Installation

npm install geoip-flag

Usage

Client-Side (Browser)

Call getLocationByIP() without an IP address to automatically detect the user's public IP address:

import { getLocationByIP } from 'geoip-flag';

async function getUserLocation() {
  try {
    const location = await getLocationByIP();
    console.log(location);
    // Example output:
    // {
    //   ip: '8.8.8.8',
    //   city: 'Mountain View',
    //   region: 'California',
    //   region_code: 'CA',
    //   country_code: 'US',
    //   country_code_iso3: 'USA',
    //   country_name: 'United States',
    //   country_capital: 'Washington',
    //   country_tld: '.us',
    //   continent_code: 'NA',
    //   in_eu: false,
    //   postal: '94035',
    //   latitude: 37.386,
    //   longitude: -122.0838,
    //   timezone: 'America/Los_Angeles',
    //   utc_offset: '-0700',
    //   country_calling_code: '+1',
    //   currency: 'USD',
    //   currency_name: 'Dollar',
    //   languages: 'en-US,es-US,haw',
    //   asn: 'AS15169',
    //   org: 'Google LLC',
    //   countryFlag: '🇺🇸'
    // }
  } catch (error) {
    console.error(error.message);
  }
}

getUserLocation();

Server-Side (Node.js with Express)

Extract the client's IP address from the HTTP request and pass it to getLocationByIP(ipAddress):

const express = require('express');
const { getLocationByIP } = require('geoip-flag');

const app = express();
app.set('trust proxy', true); // Enable if behind a proxy like Nginx

app.get('/location', async (req, res) => {
  try {
    const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
    const location = await getLocationByIP(clientIp);
    res.json(location);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Using with a Specific IP Address

Provide an IP address explicitly to get geolocation data for that IP:

const { getLocationByIP } = require('geoip-flag');

async function getLocation() {
  try {
    const location = await getLocationByIP('8.8.8.8');
    console.log(location);
  } catch (error) {
    console.error(error.message);
  }
}

getLocation();

TypeScript Usage

The package includes type definitions for TypeScript:

import { getLocationByIP } from 'geoip-flag';

async function getUserLocation() {
  try {
    const location = await getLocationByIP();
    console.log(location);
  } catch (error) {
    console.error(error instanceof Error ? error.message : 'Unknown error');
  }
}

getUserLocation();

Features

• Automatically detects the user's IP address when no IP is provided (client-side or server-side with proper IP extraction).
• Returns comprehensive geolocation data:
  • IP address
  • City, region, and region code
  • Country code (ISO 3166-1 alpha-2), ISO3 code, and country name
  • Country capital, top-level domain (TLD), and continent code
  • EU membership status
  • Postal code, latitude, and longitude
  • Timezone and UTC offset
  • Country calling code, currency, and currency name
  • Languages spoken
  • Autonomous System Number (ASN) and organization
  • Country flag emoji
• Uses the reliable ipapi.co API for geolocation
• TypeScript support for type safety
• Lightweight with minimal dependencies (only axios)

Requirements

• Node.js >= 14
• Internet connection for API calls
• For server-side usage, ensure proper client IP extraction (e.g., handle X-Forwarded-For headers if behind a proxy).

Notes

• The package uses the free tier of ipapi.co, which has a rate limit of 1,000 requests/day. For production use, consider a paid plan or alternative geolocation API.
• In server-side applications, extract the client’s IP from the HTTP request to get accurate user location data.
• Flag emojis are generated using Unicode regional indicator symbols and may render differently on some platforms.
• Ensure users are informed that their IP address is sent to ipapi.co for geolocation purposes, as this involves sharing personal data.

License

MIT