PHP IP geolocation guide

Get country, city and approximate coordinates for one IP address in PHP.

Look up an IP address in PHP

The request accepts one IPv4 or IPv6 address and asks for JSON. Replace the example address with the address you need to inspect.

Single-IP location request

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

Requires PHP with the cURL extension. The connection timeout is three seconds and the total request limit is eight seconds.

Read the location fields

location.country_code is the two-letter country code; location.country is the country name. location.city may be empty even when the country is known. Keep an empty value as unknown.

location.latitude and location.longitude are approximate coordinates for the network location. Check for a usable location label before displaying them; numeric coordinates alone do not establish a location. They do not identify a device or person.

For the address making the request, call https://api.ipquery.io/?format=json. A server request returns the server’s connecting IP; a browser request returns its visible connection.

All response fields

Accuracy and security

IP geolocation is a network estimate, not a device location. VPNs, proxies, mobile networks and carrier gateways may place the address far from the user. Treat missing values as unknown rather than filling in a guess.

If your application reads X-Forwarded-For, trust it only when a proxy you control supplies it. Client-supplied headers can be forged. Validate addresses before making lookup requests and handle timeouts and HTTP errors separately from a successful result.

API reference