Geolocate an IP address: 4 simple signals for a safe guess

To geolocate an IP address, keep the question narrow: where is this address registered or routed? IP geolocation answers that question. where is this address registered or routed? The answer is useful for language defaults, tax rules, fraud checks and regional content. It is not a street address and it is not a person.

The IP Geolocation endpoint returns a country code by default. With full=1 it adds city, region, coordinates and a region name.

curl "https://api2.globus.studio/v2/geo?ip=8.8.8.8&format=json&full=1"

How to geolocate an IP address from the response

country is a two-letter code in lower case. city and region come from the database and can be empty. latitude and longitude point to an approximate location, often a city center. The full response keeps the old lower-case values for compatibility.

Private addresses return an error. A missing or invalid IP returns {"error":true,"message":"IP address not found"}. Plan for that case instead of assuming every lookup succeeds.

Accuracy

In a geolocate an IP address result, country accuracy is high. A geolocate an IP address call is a default, not an identity. City accuracy is lower, especially for mobile networks, VPNs and corporate egress. A request from a phone may appear in the city where the carrier routes traffic, not where the user stands. A VPN can put the address in another country.

Use the country for legal and language decisions. Use the city for rough grouping, not for delivery or identity. If the decision affects money or access, combine the lookup with another signal.

A practical use

To geolocate an IP address for a storefront, use the country code from the response for the default currency and language. Cache the result per address for a day. If the user changes the setting, store the choice and stop guessing on later requests.

$geo = json_decode(file_get_contents(
    'https://api2.globus.studio/v2/geo?ip=' . urlencode($ip) . '&format=json'
), true);
$locale = ($geo['country'] ?? '') === 'de' ? 'de-DE' : 'en-GB';

IPv6 and proxy headers

The endpoint accepts IPv6 addresses. If your application sits behind a proxy, resolve the client address before calling the API. The geolocation of a proxy is the geolocation of the proxy, not the user.

Limits

The data set behind a geolocate an IP address call is updated on a schedule, so very recent allocations can be missing. Unknown values are returned as a dash. The endpoint is rate limited like the rest of the catalog. Cache responses when you can.

Read the full documentation for parameters, examples and the complete response shape.

Country and city serve different decisions

Country is stable enough for tax, language and legal notices. City is not. A city-level result can be a routing hub, a carrier gateway or a data center. Use it to group traffic in a report, not to decide whether a transaction is valid.

For a storefront, the country code can choose a default currency and a language. Let the customer override both. For fraud checks, a mismatch between the billing country and the IP country is one signal among several. Do not reject an order on that signal alone.

Caching keys

Cache the response by address, not by user. An IPv6 address has more characters than an IPv4 address, so the cache key needs room. Normalize the address before the lookup. A compressed IPv6 form and an expanded form should map to the same key.

$key = 'geo:' . inet_ntop(inet_pton($ip));

VPNs and corporate egress

A single geolocate an IP address result should not decide whether a transaction is valid. A VPN moves the visible address to the VPN exit. A corporate network can route every office through one country. The lookup reports the exit, which is the correct answer for the network path and the wrong answer for the person. Use the result as a default, and let the user correct it.

Geolocating an IP address: what the data can and cannot tell you