Reference
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ip |
string | yes | IPv4 or IPv6 address. |
format |
string | no | plain, json, jsonp. Default: plain. |
full |
bool | no | Add city, region and coordinates. Default: false. |
callback |
string | no | JSONP callback name. Default: callback. |
Example request
curl -s "https://api2.globus.studio/v2/geo?ip=8.8.8.8&full=true"
An IP geolocation API call answers a narrow question: where is this address registered or routed? The answer fits a default language, a currency, a regional notice or a rough traffic report. It does not name a person and it does not give a street address.
What an IP geolocation API returns
An IP geolocation API response is a two-letter country code in lower case by default. Add full=1 to get the city, the region code, the region name, latitude and longitude. Unknown values come back as a dash, so a client should handle an empty city without failing.
{
"country": "us",
"city": "mountain view",
"region": "us-ca",
"latitude": "37.38605",
"longitude": "-122.08385",
"region_name": "california"
}
The full response keeps lower-case values for compatibility with the old contract. A client that needs upper case can convert the code at the edge.
Country and city are different decisions
An IP geolocation API result has high country accuracy. City accuracy is lower, especially for mobile networks, VPNs and corporate egress. A phone can appear in the city where the carrier routes traffic. A VPN can put the address in another country. Use the country for tax, language and legal notices. Use the city to group a report, not to decide whether a payment is valid.
IPv6 and proxy headers
An IP geolocation API call accepts IPv4 and IPv6. If the application sits behind a proxy, resolve the client address before calling the API. The geolocation of a proxy is the geolocation of the proxy. A private address returns an error, and a missing or invalid address returns {"error":true,"message":"IP address not found"}.
Errors and missing values
Treat a dash as unknown. Do not copy the previous value into the field. A missing value can come from a new allocation, a private range or a database gap, and each case needs the same fallback in the client code. If the country is missing, fall back to a default locale and let the user change it. A hard failure at that point removes a working page for a reason the visitor cannot fix.
Language and currency defaults
A country code is a good default and a poor instruction. A visitor in Germany may read English, and a visitor in Canada may pay in US dollars. Use the geolocation result to pick the first value, then store the visitor choice and apply it on the next request. The page should not change language under the user on every visit.
For a currency, show the local price and the charged currency. A conversion rate needs a timestamp, and the checkout should use the payment provider rate for the final amount. The geolocation result chooses the display, not the charge.
Rate limits and caching
An IP geolocation API call is fast and rate limited. Cache the result per address for a day. An address can change network, but a daily refresh is enough for a locale default. When the visitor chooses a language or a currency, store that choice and stop guessing on later requests.
When to use an IP geolocation API
Choose a default language or currency, group traffic in a report or add context to a fraud check. In a checkout, a mismatch between the billing country and the IP country is one signal among several. Rejecting an order on that signal alone will catch a traveller and a corporate VPN along with the fraud.
GET https://api2.globus.studio/v2/geo?ip=8.8.8.8&format=json&full=1
Related endpoints
To read the caller address first, use the public IP address API. For a mobile network, see the carrier detection endpoint. The geolocation guide covers caching and the cases where city data misleads.
Further reading: ISO 3166 country codes.