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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.k9.io/key9-identity/maxmind-api-proxy/api-reference/lookup-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.