Introduction

maxmind-api-proxy is a lightweight Go service that sits between your internal clients and the MaxMind GeoIP2 API. 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