> 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/getting-started/quick-start.md).

# 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

```bash
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:

```bash
cp etc/config.json my-config.json
```

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

```json
{
  "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](/key9-identity/maxmind-api-proxy/configuration/tls.md) for production HTTPS configuration.

***

## Step 3 — Start the proxy

```bash
./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

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

A successful response returns JSON from MaxMind:

```json
{
  "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](/key9-identity/maxmind-api-proxy/configuration/configuration.md) — all available options explained
* [TLS / HTTPS Setup](/key9-identity/maxmind-api-proxy/configuration/tls.md) — secure the proxy endpoint for production
* [Running as a Service](/key9-identity/maxmind-api-proxy/deployment/service.md) — run the proxy under systemd or launchd