JavaScript SDK

@netloc8/core — Universal IP geolocation client for Node.js, Bun, Deno, Cloudflare Workers, and the browser.

Installation

Bash

bun add @netloc8/core

Also available via npm, yarn, or pnpm.

Quick Start

JavaScript

import { fetchGeo } from '@netloc8/core';

const geo = await fetchGeo('8.8.8.8', {
    apiKey: process.env.NETLOC8_API_KEY,
});

console.log(geo.location?.country?.name); // "United States"
console.log(geo.location?.city);          // "Mountain View"
console.log(geo.location?.timezone);      // "America/Los_Angeles"

All Exports

Export	Type	Description
`fetchGeo`	function	Look up geolocation for a specific IP address
`fetchMyGeo`	function	Look up geolocation for the calling IP (browser)
`fetchTimezone`	function	Get IANA timezone for a specific IP
`fetchMyTimezone`	function	Get IANA timezone for the calling IP (browser)
`isEU`	function	Check if a Geo location is in the EU (GDPR)
`getClientIp`	function	Extract client IP from request headers
`isPublicIp`	function	Check whether an IP is publicly routable
`getGeoFromPlatformHeaders`	function	Parse Vercel / Cloudflare / CloudFront geo headers
`parseCookie / serializeCookie`	function	Read/write the __netloc8 geo cookie
`reconcileGeo`	function	Deep-merge cookie, platform, and API geo sources
`normalizeApiResponse`	function	Normalize raw API JSON into a Geo object
`getTimezone / getLanguage`	function	Browser signal helpers for cross-validation

fetchGeo

Looks up the geolocation of a specific IPv4 or IPv6 address.

JavaScript

import { fetchGeo } from '@netloc8/core';

const geo = await fetchGeo('203.0.113.42', {
    apiKey: 'sk_live_YOUR_KEY',
    // Optional: override the API base URL
    // apiBase: 'https://custom-proxy.example.com/api/geo',
});

// Full response shape — see Response Format docs
console.log(geo.location?.country);     // { code: 'US', name: 'United States', flag: '🇺🇸' }
console.log(geo.location?.coordinates); // { latitude: 37.386, longitude: -122.084 }

fetchMyGeo

Looks up the geolocation of the requesting client's own IP address. Equivalent to GET /v1/ip/me.

JavaScript

import { fetchMyGeo } from '@netloc8/core';

// In the browser — uses publishable key
const geo = await fetchMyGeo({
    apiKey: 'pk_live_YOUR_KEY',
});

console.log(`You are in ${geo.location?.city}`);

fetchTimezone / fetchMyTimezone

Returns just the IANA timezone string (e.g. America/Chicago). More lightweight than a full geo lookup.

JavaScript

import { fetchTimezone, fetchMyTimezone } from '@netloc8/core';

const tz = await fetchTimezone('8.8.8.8', {
    apiKey: 'sk_live_YOUR_KEY',
});
console.log(tz); // "America/Los_Angeles"

// Or detect the caller's timezone:
const myTz = await fetchMyTimezone({ apiKey: 'pk_live_YOUR_KEY' });

isEU

Checks whether a geolocation response is in the European Union. Useful for GDPR consent flows.

JavaScript

import { fetchMyGeo, isEU } from '@netloc8/core';

const geo = await fetchMyGeo({ apiKey: 'pk_live_YOUR_KEY' });

if (isEU(geo)) {
    showCookieConsentBanner();
}

EU Detection

isEU() checks location.country.unions for "EU" membership. This covers all current EU member states. EEA-only countries (Norway, Iceland, Liechtenstein) are not included — handle those separately if needed.

Browser Signal Collection

In the browser, the SDK can collect signals like Intl.DateTimeFormat timezone and navigator.language for cross-validation with IP-based results.

JavaScript

import { getBrowserHeaders } from '@netloc8/core';

// Returns { 'X-Browser-Timezone': '...', 'X-Browser-Locale': '...', ... }
const headers = getBrowserHeaders();

These headers are automatically included when using fetchMyGeo() in a browser environment. The API uses them to improve accuracy.

Error Handling

All fetch functions return null on error — they never throw. Errors are logged to the console with structured error codes when available.

JavaScript

const geo = await fetchGeo('203.0.113.42', {
    apiKey: process.env.NETLOC8_API_KEY,
});

if (!geo) {
    // fetchGeo logged the error automatically, e.g.:
    // [netloc8] Geo lookup failed for 203.0.113.42: INVALID_IP (HTTP 400)
    console.log('Geo lookup failed — proceeding without geo data');
}

Configuration Options

Option	Type	Default	Description
`apiKey`	string	—	Your NetLoc8 API key (required unless allowAnonymous)
`apiBase`	string	https://api.netloc8.com	Override the API base URL (for proxies)
`timeout`	number	5000	Request timeout in milliseconds
`allowAnonymous`	boolean	false	Allow requests without an API key