> For the complete documentation index, see [llms.txt](https://docs.k9.io/key9-identity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.k9.io/key9-identity/maxmind-api-proxy/api-reference/lookup-endpoint.md).

# 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](/key9-identity/maxmind-api-proxy/api-reference/authentication.md). |

### Example requests

```bash
# 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](/key9-identity/maxmind-api-proxy/api-reference/response-format.md) for field details.

```json
{
  "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:

```json
{
  "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](/key9-identity/maxmind-api-proxy/caching/overview.md).

***

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