Geolocalização do visitante para o seu website

Chame GET /v1/geo diretamente a partir do navegador de um visitante para obter o país, cidade, fuso horário e contexto regional disponíveis dessa ligação. Configure a sua origem permitida, adicione a sua chave publicável e decida como a sua aplicação deve tratar a resposta.

Obter uma chave de API de visitante gratuita Ler o início rápido →

O pedido provém do navegador do visitante

GET /v1/geo descreve sempre o cliente que se liga a ele. Chame-o a partir do navegador do visitante para receber os dados de localização dessa ligação; um pedido enviado a partir do servidor da sua aplicação descreve a própria ligação do servidor, não a do visitante. Se já tiver o endereço IP de um utilizador final e precisar de o resolver a partir do seu back-end, utilize a API de pesquisa de IP separada. A chave de visitante é publicável — foi concebida para aparecer em código do navegador — pelo que o verdadeiro controlo é a lista de origens permitidas configurada para ela, e não o sigilo da própria chave.

Conceba isto como uma sugestão, não um redirecionamento forçado

Um viajante pode utilizar uma rede num país enquanto prefere outra língua, e uma VPN pode colocar uma ligação totalmente noutro local. Dê aos visitantes uma forma visível de alterar a língua, país ou moeda sugeridos, e preserve essa escolha em vez de a voltar a derivar da localização em cada visita.

Contexto de segurança apenas em planos elegíveis

Nos planos que o incluem, a resposta pode conter indicadores baseados em listas de VPN/Tor/ameaça. Um objeto security omitido significa que o campo não está incluído no seu plano, não que a rede foi considerada segura; um valor false significa que não houve correspondência nos dados de origem disponíveis, o que não é o mesmo que um atestado de segurança limpo. A cobertura varia consoante o indicador e a versão de IP — a deteção de Tor em IPv6, por exemplo, não está atualmente implementada.

Contexto útil na resposta

country, region, city, latitude, longitude: Localização aproximada do pedido em ligação. Não é uma posição de dispositivo ou GPS, nem prova do paradeiro de uma pessoa específica.
timezone, currency, callingCode: Contexto regional derivado da localização resolvida, útil como sugestão inicial.
asn, asOrganization: A rede em ligação e o seu operador, quando disponível. Um nome de organização não é a identidade de uma pessoa.
security: Omitido por completo salvo se o seu plano o incluir. Quando presente: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — indicadores baseados em listas, não uma garantia de segurança.

Adicione o primeiro pedido

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

Substitua o marcador de posição pela sua chave de visitante e execute a página a partir de uma origem permitida para essa chave. Mantenha a experiência predefinida do seu site disponível caso o pedido falhe ou um campo esteja em falta.

Perguntas frequentes

Isto pede permissão de localização do dispositivo?

Não. O pedido baseado em IP não utiliza a API de Geolocalização do dispositivo do navegador — estima a localização a partir da ligação em vez de pedir coordenadas fornecidas pelo dispositivo. As suas próprias obrigações de privacidade e consentimento continuam a depender de como a sua aplicação utiliza o resultado.

Posso passar um endereço IP para /v1/geo?

Não. O endpoint descreve sempre o cliente em ligação. Utilize /v1/lookup/{ip} a partir do seu back-end quando quiser fornecer um endereço.

Porque é que um pedido renderizado no servidor mostra a localização do meu fornecedor de alojamento?

O servidor é o cliente em ligação para esse pedido. Mova o pedido de visitante para código do navegador, ou utilize o endpoint de pesquisa de IP a partir do seu back-end com uma fonte fiável do IP do utilizador final.

A cidade ou as coordenadas são exatas?

Não. A geolocalização por IP é uma estimativa associada à ligação, não a posição precisa de uma pessoa.

Posso utilizar uma chave secreta no navegador?

Não. Utilize uma chave de visitante publicável para este endpoint, e mantenha as chaves secretas de pesquisa apenas no ambiente do seu back-end.