Quick Start

This guide gets the proxy running locally in under five minutes. It assumes you have Go installed, Redis running on localhost:6379, and a MaxMind account with GeoIP2 Precision API access.

---

Step 1 — Build the binary

git clone https://github.com/k9io/maxmind-api-proxy.git
cd maxmind-api-proxy
go mod tidy
go build -o maxmind-api-proxy

---

Step 2 — Create a configuration file

Copy the example config and edit it:

cp etc/config.json my-config.json

Open my-config.json and fill in your values:

{
  "api_key": "my-strong-secret-key",
  "cache_errors": false,

  "http_listen": ":8080",
  "http_tls": false,
  "http_cert": "",
  "http_key": "",
  "http_mode": "release",

  "maxmind_username": "123456",
  "maxmind_password": "your_maxmind_license_key",
  "maxmind_url": "https://geoip.maxmind.com/geoip/v2.1/city/",

  "redis_host": "127.0.0.1",
  "redis_port": 6379,
  "redis_password": "your_redis_password",
  "redis_database": "0",
  "redis_cache_time": 24
}

Note: http_cert and http_key must be present in the config file even when http_tls is false. You can set them to any non-empty placeholder value. See TLS Setup for production HTTPS configuration.

---

Step 3 — Start the proxy

./maxmind-api-proxy my-config.json

You should see output similar to:

2025/06/12 10:00:00 Firing up Maxmind-API-Proxy!
2025/06/12 10:00:00 Connect to Redis.
2025/06/12 10:00:00 Setting gin to "release" mode.
2025/06/12 10:00:00 Listening for traffic on :8080.

---

Step 4 — Query the proxy

curl -H 'API_KEY: my-strong-secret-key' http://localhost:8080/8.8.8.8

A successful response returns JSON from MaxMind:

{
  "city": { "names": { "en": "Mountain View" } },
  "country": { "iso_code": "US", "names": { "en": "United States" } },
  "location": { "latitude": 37.386, "longitude": -122.0838, "time_zone": "America/Los_Angeles" },
  ...
}

Query the same IP a second time — the response comes from the Redis cache and is noticeably faster.

---

Next steps

• Configuration File Reference — all available options explained

• TLS / HTTPS Setup — secure the proxy endpoint for production

• Running as a Service — run the proxy under systemd or launchd