Geolocalización de visitantes para tu sitio web

Llama a GET /v1/geo directamente desde el navegador de un visitante para obtener el país, la ciudad, la zona horaria y el contexto regional disponibles de esa conexión. Configura tu origen permitido, agrega tu clave publicable y decide cómo debe manejar tu aplicación la respuesta.

Obtén una clave de API de visitante gratuita Lee la guía rápida →

La solicitud proviene del navegador del visitante

GET /v1/geo siempre describe al cliente que se conecta a él, sea cual sea. Llámalo desde el navegador del visitante para recibir los datos de ubicación de esa conexión; una solicitud enviada desde el servidor de tu aplicación describe la propia conexión del servidor, no la del visitante. Si ya tienes la dirección IP de un usuario final y necesitas resolverla desde tu backend, usa la API de búsqueda de IP independiente. La clave de visitante es publicable — está diseñada para aparecer en código de navegador — así que el control real es la lista de orígenes permitidos configurada para ella, no el secreto de la clave en sí.

Diseña para una sugerencia, no una redirección forzada

Un viajero puede usar una red en un país mientras prefiere otro idioma, y una VPN puede ubicar una conexión en un lugar completamente distinto. Ofrece a los visitantes una forma visible de cambiar el idioma, país o moneda sugeridos, y conserva esa elección en lugar de volver a derivarla de la ubicación en cada visita.

Contexto de seguridad solo en planes elegibles

En los planes que lo incluyen, la respuesta puede contener indicadores de VPN/Tor/amenaza basados en listas. Un objeto security omitido significa que el campo no está incluido en tu plan, no que la red se haya verificado y encontrado segura; un valor false significa que no hubo coincidencia en los datos de origen disponibles, lo cual no es lo mismo que un certificado de limpieza. La cobertura difiere según el indicador y la versión de IP — la detección de Tor sobre IPv6, por ejemplo, no está implementada actualmente.

Contexto útil en la respuesta

country, region, city, latitude, longitude: Ubicación aproximada de la solicitud entrante. No es una posición de dispositivo o GPS, ni evidencia del paradero de una persona específica.
timezone, currency, callingCode: Contexto regional derivado de la ubicación resuelta, útil como sugerencia inicial.
asn, asOrganization: La red que se conecta y su operador, cuando están disponibles. Un nombre de organización no es la identidad de una persona.
security: Se omite por completo a menos que tu plan lo incluya. Cuando está presente: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — indicadores basados en listas, no una garantía de seguridad.

Agrega la primera solicitud

JavaScript de navegador

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 };
}

Reemplaza el marcador de posición con tu clave de visitante y ejecuta la página desde un origen permitido para esa clave. Mantén disponible la experiencia predeterminada de tu sitio si la solicitud falla o falta un campo.

Preguntas frecuentes

¿Esto solicita permiso de ubicación del dispositivo?

No. La solicitud basada en IP no usa la API de geolocalización de dispositivo del navegador — estima la ubicación a partir de la conexión en lugar de solicitar coordenadas proporcionadas por el dispositivo. Tus propias obligaciones de privacidad y consentimiento siguen dependiendo de cómo tu aplicación use el resultado.

¿Puedo pasar una dirección IP a /v1/geo?

No. El endpoint siempre describe al cliente que se conecta. Usa /v1/lookup/{ip} desde tu backend cuando quieras proporcionar una dirección.

¿Por qué una solicitud renderizada por el servidor muestra la ubicación de mi proveedor de hosting?

El servidor es el cliente que se conecta para esa solicitud. Mueve la solicitud de visitante a código de navegador, o usa el endpoint de búsqueda de IP desde tu backend con una fuente confiable de la IP del usuario final.

¿Es exacta la ciudad o la coordenada?

No. La geolocalización de IP es una estimación asociada a la conexión, no la posición precisa de una persona.

¿Puedo usar una clave secreta en el navegador?

No. Usa una clave publicable de visitante para este endpoint, y mantén las claves secretas de búsqueda solo en el entorno de tu backend.