Public IP address

curl -s "https://api2.globus.studio/v2/ip?format=json"

The public IP address API returns the address that reached the server. It reads the connection and, when the request comes from a trusted proxy, the forwarded header. A script, a log line or a health check can ask the endpoint instead of parsing a chain of headers. A public IP address answer is one value, so the common case needs no parser.

What the public IP address API returns

The default response is plain text with one value: the caller address. Ask for JSON when the caller needs a field name. The JSON body has one key, ip, and the plain body has the address alone.

curl "https://api2.globus.studio/v2/ip"
curl "https://api2.globus.studio/v2/ip?format=json"

{"ip":"8.8.8.8"}

Response formats

The format parameter accepts plain, json and jsonp. Plain is the default. JSONP wraps the object in the callback name from the callback parameter, which is useful for an old browser client. A modern client should use JSON and a normal fetch.

The content type matches the body. A plain response is text/plain; a JSON response is application/json. A client that checks the header will parse the answer correctly.

IPv4 and IPv6

A public IP address request can ask for one address family with the v parameter. Pass v=4 or v=6. When the caller connects over the other family, the response is a dash. That is a normal answer: the caller has no address in the requested family. Do not treat the dash as an error.

Store the result in a column that accepts both families. A 15-character field is too small for IPv6. Normalize the value before you compare it with a block list; an IPv4-mapped IPv6 address and the plain form are different strings.

Proxy headers and trusted proxies

Behind Cloudflare, nginx or another proxy, the connection address belongs to the proxy. The original client is in a forwarded header. A header can be forged, so the endpoint reads it only when the request comes from an address in security.trusted_proxies.

Add every proxy address to that list, including a load balancer in front of the web server. If the list is empty or incomplete, the response contains the proxy address. That is the correct answer for the connection the server sees, and it is the reason a local test can differ from production.

Errors and edge cases

The endpoint has no required parameters, so a bad request is rare. A wrong v value falls back to the default family. A missing address in the requested family returns a dash. If the service cannot parse the connection, the response is empty rather than a guess.

A JSONP callback name should contain only letters, digits and underscores. Treat the response as data, not as code, and never evaluate it in a context where an attacker controls the callback.

Rate limits and caching

The call is cheap, so it can run from a health check or a request logger. It is still rate limited. Cache the answer for the life of the request; the caller address does not change between two calls in the same request. Do not cache it across users.

When to use the public IP address API

The public IP address API also answers a support question: which address does this host actually use? Use it to read the caller address in a script, add the address to a log line or confirm which address your own stack sends upstream. It also helps when a firewall rule or an allow list does not behave as expected: call the endpoint from the same host and compare the result with the rule.

Pair it with the IP geolocation API when you need the country, and with IP bot detection when the address is a signal in a larger decision.

Related endpoints

A public IP address API call is the first step in most request logs. Read the full guide on getting a visitor IP address for the proxy rules in PHP and Node. For a country or a city, open the geolocation endpoint. For a policy around anonymous traffic, start with the Tor check.

Further reading: RFC 7239, Forwarded HTTP Extension.