# nominatim

Self-hosted [Nominatim](https://nominatim.org/) (OpenStreetMap geocoding)
for address search / soft validation on the homelab LAN. Pure OSM data,
**no API key**, no per-request cost.

Companion to [Ditch_The_Agent/OSRM](https://git.aimloperations.com/Ditch_The_Agent/OSRM)
(routing) on **ai-server-4080** (`10.0.0.128`).

> **OSRM ≠ Nominatim.** OSRM routes lat/lng. Nominatim turns addresses into
> coordinates (and reverse). Share the **`.osm.pbf` only** — never mount
> OSRM `.osrm*` graph files into this stack.

Consumers (e.g. `monica_site`) should use:

```bash
NOMINATIM_BASE_URL=http://10.0.0.128:8089
```

Provisioning: [server-infra#16](https://git.aimloperations.com/ai_ml_operations/server-infra/issues/16).

---

## What you get

* `mediagis/nominatim` Docker image (upstream)
* HTTP API on host port **8089** (container `8080`):
  * `/search` — forward geocode
  * `/reverse` — reverse geocode
  * structured params: `street`, `city`, `state`, `postalcode`, `country`
* First boot imports a local PBF into an internal Postgres/PostGIS volume

---

## Hardware sizing (rough)

| Region | PBF size | Import RAM | Serve RAM | Disk (DB) |
|--------|----------|------------|-----------|-----------|
| US single state (e.g. Ohio) | ~200–400 MB | ~8–16 GB | ~2–4 GB | ~10–30 GB |
| US Midwest extract | ~1–3 GB | ~16–32 GB | ~4–8 GB | ~40–100 GB |
| Full US | ~10+ GB | 64 GB+ | 16 GB+ | 200 GB+ |

Import is one-shot and slow. Prefer the **smallest extract** that covers
your service area (Ohio / Midwest for monica_site). Full US is optional
and expensive on disk/RAM.

---

## Quick start

```bash
# from this directory
mkdir -p data
cp .env.example .env
# edit NOMINATIM_PASSWORD + NOMINATIM_PBF_FILE if needed

# 1. Place (or symlink) a Geofabrik PBF into ./data/
#    Reuse the same PBF used for OSRM — copy/symlink, do not move OSRM's copy
#    if OSRM still needs it.
ln -sf /path/to/OSRM/data/us-latest.osm.pbf data/region.osm.pbf
# or download a smaller extract:
# curl -L -o data/ohio-latest.osm.pbf \
#   https://download.geofabrik.de/north-america/us/ohio-latest.osm.pbf

# 2. First up runs the import (long). Keep the container running afterward.
docker compose up -d

# 3. Watch import / API ready
docker compose logs -f nominatim

# 4. Smoke test
curl -sG 'http://localhost:8089/search' \
  --data-urlencode 'q=Akron, OH' -d 'format=json' -d 'limit=1'
```

Structured address check:

```bash
curl -sG 'http://localhost:8089/search' \
  -d 'street=123 Main St' \
  -d 'city=Akron' \
  -d 'state=Ohio' \
  -d 'postalcode=44301' \
  -d 'country=USA' \
  -d 'format=json' \
  -d 'limit=1'
```

---

## Running the container

```bash
docker compose pull
docker compose up -d
docker compose logs -f nominatim
docker compose ps
docker compose restart nominatim
docker compose stop
docker compose down   # keeps named volume with DB unless -v
```

Set `NOMINATIM_PBF_FILE` in `.env` to the filename under `./data/`
(default `region.osm.pbf`).

Import only runs when the Postgres data volume is empty. To re-import:

```bash
docker compose down -v   # destroys nominatim-pgdata
# ensure data/*.osm.pbf is present
docker compose up -d
```

---

## Homelab LAN (adama / roslin → ai-server-4080)

Default bind is `0.0.0.0:8089` so LAN hosts can reach it. Open UFW to the
LAN only — **not** the public internet:

```bash
sudo ufw allow from 10.0.0.0/24 to any port 8089 proto tcp comment 'Nominatim homelab LAN'
sudo ufw status
```

Verify from another host:

```bash
curl -sG 'http://10.0.0.128:8089/search' \
  --data-urlencode 'q=Akron, OH' -d 'format=json' -d 'limit=1'
```

Local-only bind: set `NOMINATIM_BIND_HOST=127.0.0.1` in `.env`.

---

## Relation to OSRM

| | OSRM (`:5000`) | Nominatim (`:8089`) |
|--|----------------|---------------------|
| Job | Route coordinates | Geocode addresses |
| Input | `.osrm*` graphs | `.osm.pbf` → Postgres |
| Share | — | **PBF only** |

Typical app flow: Nominatim search → lat/lng → (optional) OSRM route.

---

## License / attribution

Nominatim is GPL-2.0. OpenStreetMap data is © OpenStreetMap contributors,
ODbL. Attribute on any UI that surfaces geocoded results:

> "Geocoding © OpenStreetMap contributors, via Nominatim."