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

Parameter	Type	Description
ip_address	string	The IPv4 or IPv6 address to look up. Must be a valid IP address.

Required header

Header	Description
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::8888

---

Response

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.

{
  "city": {
    "geoname_id": 5375480,
    "names": { "en": "Mountain View" }
  },
  "country": {
    "iso_code": "US",
    "names": { "en": "United States" }
  },
  "location": {
    "accuracy_radius": 1000,
    "latitude": 37.386,
    "longitude": -122.0838,
    "time_zone": "America/Los_Angeles"
  },
  ...
}

Error responses

Status	Body	Cause
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:

{
  "code": "IP_ADDRESS_NOT_FOUND",
  "error": "The supplied IP address is not in the database."
}

Whether this response is cached depends on the cache_errors setting. See How Caching Works.

---

Behaviour at a glance

Request → Auth check → Cache check → (if miss) MaxMind query → Cache store → Response

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).