@ipgeotrace/browser

The browser IPGeoTrace client. Answers one question — where is the person looking at this page? — via GET /resolve/me, which sees the browser's real connection IP.

Sign up and grab your publishable key at ipgeotrace.com.

Use it to personalize on the client: auto-select the visitor's country, price in their local currency, prefill a phone code, default a timezone or language.

Framework-agnostic: React, Vue, Svelte, and vanilla all use it the same way. The optional reactive wrappers (@ipgeotrace/react, etc.) are thin sugar on top; you don't need them.

Install

npm add @ipgeotrace/browser

Usage

import { createBrowserClient } from '@ipgeotrace/browser';

const client = createBrowserClient({ publishableKey: 'pk_live_...' });

const result = await client.me();
if (result.ok) {
  console.log(result.value.country?.name, result.value.location?.timeZone);
}

That's it — me() calls the API directly from the browser. It's async because it makes a network request; await it and check result.ok.

The key is a publishable key

You put this key in your client-side code on purpose. A publishable key is safe to expose because it is restricted: domain-locked to your site, scoped to resolve / me only (no batch, no account access), and rate-limited. This is the same model as a Google Maps browser key. Never ship your secret server key (@ipgeotrace/client) to the browser — that one can run batch lookups and spend your whole quota.

Publishable keys are a planned API feature (domain allowlist + resolve-only scope). Until they ship, treat this package as targeting that model. See ../../API-CONTRACT.md.

Options

createBrowserClient({
  publishableKey: 'pk_live_...',  // required
  baseUrl: undefined,             // override the API host (staging / self-hosted)
  timeoutMs: 10_000,
  fetch: globalThis.fetch,
});

me() is always a live call — it is never cached. The caller's IP can change at any time (VPN, Wi-Fi ↔ cellular, moving networks) and the browser never knows its own IP, so there is nothing safe to key a cache on. Every me() reflects the visitor's location right now. It returns the same Result<GeoResponse> shape as @ipgeotrace/client.

React, in ~30 lines (no extra package needed)

function useVisitorGeo() {
  const [state, setState] = useState<GeoResponse | null>(null);
  useEffect(() => {
    const client = createBrowserClient({ publishableKey: 'pk_live_...' });
    const controller = new AbortController();
    client.me(controller.signal).then((r) => r.ok && setState(r.value));
    return () => controller.abort();
  }, []);
  return state;
}