IP Lookup Endpoint
GET /:ip_address
Look up geolocation data for an IP address. Results are served from the Redis cache when available; otherwise the proxy queries MaxMind, caches the result, and returns it.
Request
Path parameter
ip_address
string
The IPv4 or IPv6 address to look up. Must be a valid IP address.
Required header
API_KEY
Your proxy API key. See Authentication.
Example requests
# IPv4
curl -H 'API_KEY: your-secret-key' https://yourproxy.example.com:8443/8.8.8.8
# IPv6
curl -H 'API_KEY: your-secret-key' https://yourproxy.example.com:8443/2001:4860:4860::8888Response
Success — 200 OK
Returns the raw JSON body from MaxMind. The content is identical whether it came from cache or from a live upstream query. See Response Format for field details.
Error responses
400 Bad Request
{"error": "invalid IP address"}
The path parameter is not a valid IP address.
401 Unauthorized
{"error": "api authentication failed"}
Missing or incorrect API_KEY header.
502 Bad Gateway
{"error": "upstream request failed"}
The proxy could not reach MaxMind (network error or timeout).
502 Bad Gateway
{"error": "failed to read upstream response"}
MaxMind was reached but the response could not be read.
MaxMind error in the response body
When MaxMind itself returns an error (e.g. the IP is not in its database, or your account is over quota), the proxy returns 200 OK with a JSON body containing an "error" field from MaxMind:
Whether this response is cached depends on the cache_errors setting. See How Caching Works.
Behaviour at a glance
The total round-trip for a cache hit is typically under 5 ms. A cache miss adds the MaxMind API latency (typically 20–100 ms depending on geography).
Last updated