Guia ·
Geolocalização por IP: como descobrir a localização do visitante?
Aprenda a descobrir a cidade, estado e país do visitante do seu site usando o endereço IP. Guia prático com exemplos em JavaScript e PHP para personalizar conteúdo por região.
Já percebeu como alguns sites mostram conteúdo personalizado para sua região? Preços em reais, ofertas locais, ou até a bandeira do seu país? Isso é possível graças à geolocalização por IP.
Neste guia, você vai aprender a identificar a localização dos visitantes do seu site usando uma API simples, sem pedir permissão do navegador.
O que é geolocalização por IP?
Todo dispositivo conectado à internet possui um endereço IP. Esse IP está vinculado a um provedor de internet, que por sua vez está registrado em uma localização geográfica.
Com uma API de geolocalização, você consegue descobrir:
- 🏙️ Cidade do visitante;
- 🗺️ Estado/Região;
- 🌍 País (com bandeira);
- 📍 Coordenadas (latitude e longitude);
- 🔢 WOEID (código para integrar com API de clima).
Por que usar geolocalização?
Alguns casos de uso práticos:
- 🛒 E-commerce: Mostrar preços na moeda local e calcular frete automaticamente;
- 📰 Portais de notícias: Destacar notícias da região do leitor;
- 🎯 Marketing: Personalizar ofertas por localização;
- 🔒 Segurança: Detectar acessos de localizações suspeitas;
- 🌤️ Clima: Mostrar previsão do tempo automática.
Qual API de geolocalização usar?
A
- 📍 Localização por IP (cidade, estado, país);
- 🏳️ Bandeira do país em SVG;
- 🌐 Coordenadas geográficas;
- 🔗 Integração direta com a API de clima (WOEID).
Dados em JSON com documentação em português.
Quanto custa?
O plano gratuito é suficiente para a maioria dos projetos.
Para necessidades maiores, existem
Como começar: passo a passo
1. Crie sua chave de API
- Acesse console.hgbrasil.com;
- Crie sua conta gratuita;
- Gere uma chave do tipo "uso exposto".
2. Faça sua primeira requisição
O endpoint aceita dois tipos de consulta:
| Parâmetro | Exemplo | Descrição |
|---|---|---|
address=remote | Detecta automaticamente | Usa o IP do visitante atual |
address=8.8.8.8 | IP específico | Consulta um IP específico |
GEThttps://api.hgbrasil.com/geoip?address=remote&key=suachave
Exemplo prático: detectando a localização
Vamos criar uma página que mostra a localização do visitante.
Estrutura HTML
Crie o arquivo index.html:
index.html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Sua Localização</title>
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<div class="location-card">
<p>Detectando localização...</p>
</div>
<script src="script.js"></script>
</body>
</html>
Buscando a localização
Crie o arquivo script.js:
script.js
const API_KEY = 'SUA_CHAVE_AQUI'
const card = document.querySelector('.location-card')
// Usa "remote" para detectar o IP do visitante automaticamente
const url = `https://api.hgbrasil.com/geoip?key=${API_KEY}&format=json-cors&address=remote`
fetch(url)
.then((response) => response.json())
.then((data) => {
const location = data.results
card.innerHTML = `
<div class="location-header">
<img class="location-flag" src="${location.country.flag.svg}" alt="${location.country.name}" />
<div class="location-country">${location.country.name}</div>
</div>
<div class="location-city">${location.city}</div>
<div class="location-region">${location.region}</div>
<div class="location-details">
<div class="location-coords">
📍 ${location.latitude.toFixed(4)}, ${location.longitude.toFixed(4)}
</div>
<div class="location-ip">
IP: ${location.address}
</div>
</div>
`
})
.catch((error) => {
card.innerHTML = '<p class="error">Erro ao detectar localização</p>'
console.error('Erro:', error)
})
Estilizando o card
Crie o arquivo styles.css:
styles.css
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: linear-gradient(135deg, #11998e 0%, #38ef7d 100%);
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
padding: 20px;
}
.location-card {
background: white;
border-radius: 16px;
padding: 24px;
min-width: 300px;
text-align: center;
box-shadow: 0 10px 40px rgba(0, 0, 0, 0.15);
}
.location-header {
display: flex;
align-items: center;
justify-content: center;
gap: 12px;
margin-bottom: 16px;
}
.location-flag {
width: 48px;
height: 32px;
border-radius: 4px;
object-fit: cover;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.location-country {
font-size: 18px;
font-weight: 600;
color: #333;
}
.location-city {
font-size: 32px;
font-weight: 700;
color: #111;
margin-bottom: 4px;
}
.location-region {
font-size: 16px;
color: #666;
margin-bottom: 20px;
}
.location-details {
padding-top: 16px;
border-top: 1px solid #eee;
}
.location-coords {
font-size: 14px;
color: #555;
margin-bottom: 8px;
}
.location-ip {
font-size: 12px;
color: #888;
font-family: monospace;
}
.error {
color: #dc2626;
}
Use
format=json-cors para requisições do navegador. Saiba mais na Exemplo em PHP (backend)
Para aplicações server-side, use o IP real do visitante:
localizacao.php
<?php
$apiKey = 'SUA_CHAVE_AQUI';
// Obtém o IP real do visitante
$ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['HTTP_X_REAL_IP'] ?? $_SERVER['REMOTE_ADDR'];
// Faz a requisição para a API
$url = "https://api.hgbrasil.com/geoip?key={$apiKey}&address={$ip}";
$response = file_get_contents($url);
$data = json_decode($response, true);
if (!$data || !isset($data['results'])) {
die('Erro ao detectar localização.');
}
$location = $data['results'];
?>
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<title>Sua Localização</title>
</head>
<body>
<div class="location-card">
<img src="<?= htmlspecialchars($location['country']['flag']['svg']) ?>"
alt="<?= htmlspecialchars($location['country']['name']) ?>"
width="48" />
<h1><?= htmlspecialchars($location['city']) ?></h1>
<p><?= htmlspecialchars($location['region']) ?>, <?= htmlspecialchars($location['country']['name']) ?></p>
<p>
📍 <?= number_format($location['latitude'], 4) ?>,
<?= number_format($location['longitude'], 4) ?>
</p>
<p>IP: <?= htmlspecialchars($location['address']) ?></p>
</div>
</body>
</html>
Em PHP, use
$_SERVER['HTTP_X_FORWARDED_FOR'] ou $_SERVER['HTTP_X_REAL_IP'] para obter o IP real quando estiver atrás de um proxy ou CDN.Veja mais exemplos na
Alta precisão
Para obter coordenadas mais precisas, adicione o parâmetro precision=true:
script.js
const url = `https://api.hgbrasil.com/geoip?key=${API_KEY}&format=json-cors&address=remote&precision=true`
O modo de alta precisão consome mais recursos e pode ser mais lento. Use apenas quando precisar de coordenadas exatas.
A