@batchbird/geo

A lightweight Next.js package for fetching IP geolocation data and device information from Vercel headers and user agent parsing.

Features

• Get complete IP geolocation data (IP, country, continent, city, region, timezone)
• Device type detection based on screen dimensions
• User agent parsing for browser, device, and OS information
• Additional geolocation data (latitude, longitude, postal code, ISP, organization, ASN)
• TypeScript support
• Zero external API dependencies
• Simple and easy to use

Installation

npm install @batchbird/geo
# or
yarn add @batchbird/geo
# or
pnpm add @batchbird/geo

Usage

Get Complete IP and Device Information

import { getGeo } from "@batchbird/geo";

// In a route handler
export async function GET(request: Request) {
  try {
    // Pass screen dimensions as a string (e.g., "1920x1080") or object
    const geoInfo = await getGeo(request, "1920x1080");
    return Response.json(geoInfo);
  } catch (error) {
    return Response.json({ error: "Failed to fetch IP info" }, { status: 500 });
  }
}

Get Device Type Only

import { getDeviceType } from "@batchbird/geo";

// Detect device type from screen dimensions
const deviceType = getDeviceType({ screen: "1920x1080" });
// Returns: "desktop", "laptop", "tablet", "mobile", "watch", or "ultra-wide-desktop"

The getGeo() function returns an object with the following properties:

Core IP Information

• ip: IP address (from x-forwarded-for or x-real-ip headers)
• country: Country code (from x-vercel-ip-country header)
• continent: Continent name (derived from country code)
• city: City name (from x-vercel-ip-city header)
• region: Region/State name (from x-vercel-ip-country-region header)
• timezone: Timezone identifier (from x-vercel-ip-timezone header)

Additional Geolocation Data

• latitude: Latitude coordinate (from x-vercel-ip-latitude header)
• longitude: Longitude coordinate (from x-vercel-ip-longitude header)
• postalCode: Postal/ZIP code (from x-vercel-ip-postal-code header)
• isp: Internet Service Provider (from x-vercel-ip-isp header)
• org: Organization (from x-vercel-ip-org header)
• asn: Autonomous System Number (from x-vercel-ip-asn header)

Device and Browser Information

• userAgent: Raw user agent string
• deviceType: Detected device type based on screen dimensions
• browser: Browser name (parsed from user agent)
• device: Device type (parsed from user agent)
• os: Operating system (parsed from user agent)

Example Response

{
  "ip": "192.168.1.1",
  "country": "US",
  "continent": "North America",
  "city": "San Francisco",
  "region": "California",
  "timezone": "America/Los_Angeles",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "deviceType": "desktop",
  "browser": "Chrome",
  "device": "desktop",
  "os": "Mac OS",
  "latitude": "37.7749",
  "longitude": "-122.4194",
  "postalCode": "94102",
  "isp": "Cloudflare, Inc.",
  "org": "Cloudflare, Inc.",
  "asn": "AS13335"
}

Screen Parameter Format

The screen parameter accepts multiple formats:

// String format: "widthxheight"
await getGeo(request, "1920x1080");
await getGeo(request, "375x667");

// Object format: { width: number, height: number }
await getGeo(request, { width: 1920, height: 1080 });
await getGeo(request, { width: 375, height: 667 });

Device Type Detection

The package automatically detects device types based on screen dimensions:

• watch: ≤ 320x320
• mobile: ≤ 900x480 (aspect ratio < 2.5)
• tablet: ≤ 1200x1000 (aspect ratio < 1.7)
• laptop: ≤ 1600x700 (aspect ratio < 2.0)
• desktop: ≤ 2560x900 (aspect ratio < 2.5)
• ultra-wide-desktop: > 2560x1440 or high aspect ratio

Error Handling

The function includes proper error handling for invalid screen inputs and missing data:

import { getGeo } from "@batchbird/geo";

export async function GET(request: Request) {
  try {
    const geoInfo = await getGeo(request, "1920x1080");
    return Response.json(geoInfo);
  } catch (error) {
    console.error("IP info fetch failed:", error);
    return Response.json(
      {
        error: "Failed to fetch IP information",
        details: error instanceof Error ? error.message : "Unknown error",
      },
      { status: 500 }
    );
  }
}

Requirements

• Next.js 13 or later
• Vercel deployment (for IP geolocation headers)
• Node.js 18+ (for fetch API support)

Dependencies

• ua-parser-js: For parsing user agent strings

License

MIT