Self-hosting

Run your own instance. Same API as the hosted service, no API key needed, free forever under MIT.

Requirements

RAM	150 MB idle, ~300 MB under load
Disk	1.66 GB for the full planet index
CPU	Any. Single core is fine.
OS	Linux, macOS, Windows
Dependencies	None. Single static binary.

1. Download pre-built indices

# Download the binary
curl -L https://github.com/heimdall-geocoder/heimdall/releases/latest/download/heimdall-linux-x86_64 \
  -o heimdall && chmod +x heimdall

# Download indices — pick what you need
./heimdall index download --country se          # Sweden, 42 MB
./heimdall index download --country se,no,dk,fi # Nordics, 133 MB
./heimdall index download --region europe        # Europe, 800 MB
./heimdall index download --planet               # Everything, 1.66 GB

# Serve
./heimdall serve --data-dir ./data

Full list of available indices and sizes on GitHub Releases.

2. Docker

# Run with a country index
docker run -p 2399:2399 \
  -v ./data:/data \
  ghcr.io/heimdall-geocoder/heimdall serve --data-dir /data

# Or download an index first
docker run -v ./data:/data \
  ghcr.io/heimdall-geocoder/heimdall \
  index download --country se --out /data

3. Docker Compose

docker-compose.yml

services:
  heimdall:
    image: ghcr.io/heimdall-geocoder/heimdall
    command: serve --data-dir /data
    ports:
      - "2399:2399"
    volumes:
      - ./data:/data
    restart: unless-stopped
    mem_limit: 512m

4. systemd service

/etc/systemd/system/heimdall.service

[Unit]
Description=Heimdall Geocoder
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/heimdall serve --data-dir /var/lib/heimdall
Restart=always
RestartSec=5
MemoryMax=512M

[Install]
WantedBy=multi-user.target

sudo systemctl enable heimdall
sudo systemctl start heimdall
curl http://localhost:2399/search?q=test&format=json

5. Build from source

git clone https://github.com/heimdall-geocoder/heimdall
cd heimdall
cargo build --release

# Build indices from raw data (downloads automatically)
cargo run --release -p heimdall-build -- rebuild --country se,no,dk

# Serve
./target/release/heimdall serve --data-dir data/

Configuration

Flag	Env var	Default	Description
--data-dir	HEIMDALL_DATA_DIR	./data	Path to index files
--port	HEIMDALL_PORT	2399	HTTP port
--host	HEIMDALL_HOST	0.0.0.0	Bind address
--workers	HEIMDALL_WORKERS	auto	Number of worker threads (default: CPU count)
--log-level	HEIMDALL_LOG_LEVEL	info	Log level: error, warn, info, debug, trace

API compatibility

Self-hosted Heimdall uses the exact same API as api.geoheim.com. Replace https://api.geoheim.com with http://localhost:2399. No API key required. No rate limits. No restrictions.

Health check

curl http://localhost:2399/status

# Returns:
# {"status": "ok", "version": "2.4.1", "countries": 192, "index_size": "1.66 GB"}