> 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/readme.md).

# Introduction

`maxmind-api-proxy` is a lightweight Go service that sits between your internal clients and the [MaxMind GeoIP2 API](https://www.maxmind.com/en/solutions/ip-geolocation-databases-api-services). It forwards IP lookup requests to MaxMind, caches the results in Redis, and returns the cached response on subsequent queries for the same IP — reducing your upstream API usage and latency.

## Why use it?

MaxMind charges per query. If multiple services in your infrastructure look up the same IP addresses repeatedly, those queries add up. `maxmind-api-proxy`:

* **Reduces costs** by serving repeated lookups from a local Redis cache instead of hitting MaxMind each time.
* **Reduces latency** for cache hits — a local Redis read is orders of magnitude faster than a round-trip to MaxMind.
* **Centralises credentials** — only the proxy holds the MaxMind username and password; clients authenticate with a separate local API key.
* **Supports TLS** so the proxy endpoint can be exposed securely across your network.

## How it works

```
Client ──(API_KEY header)──► maxmind-api-proxy
                                    │
                              Check Redis cache
                                ┌───┴───┐
                              HIT      MISS
                                │        │
                           Return      Query MaxMind
                           cached      Store in Redis
                           result      Return result
```

1. A client sends a `GET` request to `/<ip_address>` with an `API_KEY` header.
2. The proxy checks Redis for a cached result.
3. On a **cache hit**, the cached JSON is returned immediately.
4. On a **cache miss**, the proxy queries MaxMind, stores the result in Redis with a configurable TTL, and returns the JSON to the client.

## Requirements

| Requirement     | Version                     |
| --------------- | --------------------------- |
| Go              | 1.21+                       |
| Redis           | 6+                          |
| MaxMind account | GeoIP2 Precision API access |


---

# 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/readme.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.