Guia de geolocalização IP em PHP

Consultar um endereço IP em PHP

A requisição aceita um endereço IPv4 ou IPv6 e solicita JSON. Substitua o endereço do exemplo pelo que você precisa inspecionar.

<?php
$ip = '8.8.8.8'; // Replace with a validated IPv4 or IPv6 address.
if (!filter_var($ip, FILTER_VALIDATE_IP)) {
    throw new InvalidArgumentException('Invalid IP address');
}
$url = 'https://api.ipquery.io/' . rawurlencode($ip) . '?format=json';
$handle = curl_init($url);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 8,
]);
$body = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
if ($body === false) {
    $error = curl_error($handle);
    throw new RuntimeException('IP lookup failed: ' . $error);
}
if ($status !== 200) {
    throw new RuntimeException('IPQuery returned HTTP ' . $status);
}
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (($data['ip'] ?? null) !== $ip || !isset($data['location']) || !is_array($data['location'])) {
    throw new RuntimeException('Unexpected IPQuery response');
}
$location = $data['location'];
$countryCode = strtoupper(trim((string) ($location['country_code'] ?? '')));
$city = trim((string) ($location['city'] ?? ''));
echo 'Country code: ' . ($countryCode ?: 'Unknown') . PHP_EOL;
echo 'City: ' . ($city ?: 'Unknown') . PHP_EOL;

// Coordinates describe an approximate network location, not the user.
$latitude = $location['latitude'] ?? null;
$longitude = $location['longitude'] ?? null;
if (preg_match('/^[A-Z]{2}$/', $countryCode) &&
    !in_array($countryCode, ['XX', 'ZZ'], true) &&
    is_numeric($latitude) && is_numeric($longitude)) {
    printf('Approximate coordinates: %.5f, %.5f%s', $latitude, $longitude, PHP_EOL);
}

Requer PHP com a extensão cURL. O tempo limite de conexão é de três segundos e o limite total da requisição é de oito segundos.

Ler os campos de localização

location.country_code é o código de país de duas letras; location.country é o nome do país. location.city pode estar vazio mesmo quando o país é conhecido. Mantenha um valor vazio como desconhecido.

location.latitude e location.longitude são coordenadas aproximadas da localização da rede. Verifique se há uma identificação de local utilizável antes de exibi-las; coordenadas numéricas, por si só, não estabelecem uma localização. Elas não identificam um dispositivo ou uma pessoa.

Para obter o endereço que faz a requisição, chame https://api.ipquery.io/?format=json. Uma requisição do servidor retorna o IP com o qual ele se conecta; uma requisição do navegador retorna o endereço visível da sua conexão.

Precisão e segurança

A geolocalização IP é uma estimativa da localização da rede, não de um dispositivo. VPNs, proxies, redes móveis e gateways das operadoras podem situar o endereço longe do usuário. Trate os valores ausentes como desconhecidos em vez de preenchê-los com uma suposição.

Se sua aplicação lê X-Forwarded-For, confie nele apenas quando for fornecido por um proxy que você controla. Cabeçalhos enviados pelo cliente podem ser falsificados. Valide os endereços antes de realizar consultas e trate tempos limite e erros HTTP separadamente de um resultado bem-sucedido.