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