Visitor geolocation for your website

Call GET /v1/geo directly from a visitor's browser to get that connection's available country, city, timezone, and regional context. Configure your allowed origin, add your publishable key, and decide how your application should handle the response.

Get a free visitor API key Read the quickstart →

The request comes from the visitor's browser

GET /v1/geo always describes whichever client connects to it. Call it from the visitor's browser to receive that connection's location data; a request sent from your application server describes the server's own connection, not the visitor's. If you already have an end user's IP address and need to resolve it on your backend instead, use the separate IP lookup API. The visitor key is publishable — it is designed to appear in browser code — so the real control is the allowed-origins list configured for it, not secrecy of the key itself.

Design for a suggestion, not a forced redirect

A traveler may use a network in one country while preferring another language, and a VPN can place a connection elsewhere entirely. Give visitors a visible way to change the suggested language, country, or currency, and preserve that choice instead of re-deriving it from location on every visit.

Security context on eligible plans only

On plans that include it, the response can carry list-based VPN/Tor/threat indicators. An omitted security object means the field isn't included on your plan, not that the network was found safe; a false value means no match in the available source data, which is not the same as a clean bill of health. Coverage differs by indicator and IP version — IPv6 Tor detection, for instance, is not currently implemented.

Useful context in the response

country, region, city, latitude, longitude: Approximate location for the connecting request. Not a device or GPS position, and not evidence of a specific person's whereabouts.
timezone, currency, callingCode: Regional context derived from the resolved location, useful as a starting suggestion.
asn, asOrganization: The connecting network and its operator, when available. An organization name is not a person's identity.
security: Omitted entirely unless your plan includes it. When present: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — list-based indicators, not a safety guarantee.

Add the first request

Browser JavaScript

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  const geo = await response.json();
  return { country: geo.country ?? null, city: geo.city ?? null, timezone: geo.timezone ?? null };
}

Replace the placeholder with your visitor key and run the page from an origin allowed for that key. Keep your site's default experience available if the request fails or a field is missing.

Frequently asked questions

Does this request device-location permission?

No. The IP-based request does not use the browser's device Geolocation API — it estimates location from the connection rather than requesting device-provided coordinates. Your own privacy and consent obligations still depend on how your application uses the result.

Can I pass an IP address to /v1/geo?

No. The endpoint always describes the connecting client. Use /v1/lookup/{ip} from your backend when you want to supply an address.

Why does a server-rendered request show my hosting provider's location?

The server is the connecting client for that request. Move the visitor request into browser code, or use the IP lookup endpoint from your backend with a trusted source of the end user's IP.

Is the city or coordinate exact?

No. IP geolocation is an estimate associated with the connection, not a person's precise position.

Can I use a secret key in the browser?

No. Use a publishable visitor key for this endpoint, and keep secret lookup keys in your backend environment only.