If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.

DDEV Nominatim

Overview

This add-on integrates Nominatim (OpenStreetMap search and reverse geocoding engine) into your DDEV project using the mediagis/nominatim Docker image.

By default, the add-on downloads and imports the Monaco extract from Geofabrik for quick testing and development. You can easily configure it to import any regional extract or custom OSM data.

Requirements

DDEV v1.24.10 or higher

Installation

ddev add-on get bradley-tran/ddev-nominatim
ddev restart

Note

Nominatim import can take a really long time, so on the first start, Nominatim downloads and imports the OpenStreetMap extract in the background without blocking ddev start or other services. You can follow the import progress using ddev logs -s nominatim -f. Once import completes, the API endpoints will automatically become responsive.

After installation, make sure to commit the .ddev directory to version control.

Usage

Accessing Nominatim

External (Host Browser / Tools):
- HTTP: http://<projectname>.ddev.site:8980
- HTTPS: https://<projectname>.ddev.site:8943
Internal (From web container or other services):
- http://nominatim:8080

API Endpoints

Endpoint	Description	Example
`/status`	Service and database health	`http://<projectname>.ddev.site:8980/status`
`/search`	Search by address / query	`http://<projectname>.ddev.site:8980/search?q=avenue+pasteur&format=json`
`/reverse`	Reverse geocoding (lat/lon)	`http://<projectname>.ddev.site:8980/reverse?lat=43.7384&lon=7.4246&format=json`

Useful Commands

Command	Description
`ddev describe`	View service status and exposed ports
`ddev logs -s nominatim`	View Nominatim container logs
`ddev logs -s nominatim -f`	Follow live import and request logs

Configuration

Configuration is managed via .ddev/.env.nominatim. You can configure settings using ddev dotenv set:

# Example 1: Import Germany from URL instead of Monaco
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-url="https://download.geofabrik.de/europe/germany-latest.osm.pbf"
ddev restart

# Example 2: Import from a local .osm.pbf file (placed in project root or .ddev/)
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-path="data.osm.pbf"
ddev restart

Available Options

Variable	Flag	Default	Description
`NOMINATIM_DOCKER_IMAGE`	`--nominatim-docker-image`	`mediagis/nominatim:5.3`	Nominatim Docker image and tag
`NOMINATIM_PBF_URL`	`--nominatim-pbf-url`	Monaco extract URL	URL of the `.osm.pbf` file to download and import
`NOMINATIM_PBF_PATH`	`--nominatim-pbf-path`	(empty)	Path to a local `.osm.pbf` file (e.g. `data.osm.pbf`, `/mnt/ddev_config/data.osm.pbf`, or `/var/www/html/data.osm.pbf`)
`NOMINATIM_IMPORT_STYLE`	`--nominatim-import-style`	`full`	Import detail level: `admin`, `street`, `address`, or `full`
`NOMINATIM_PASSWORD`	`--nominatim-password`	`nominatim`	PostgreSQL password for nominatim user
`NOMINATIM_THREADS`	`--nominatim-threads`	`2`	Number of threads used during import
`NOMINATIM_REPLICATION_URL`	`--nominatim-replication-url`	(empty)	Base URL for live updates from Geofabrik
`NOMINATIM_IMPORT_WIKIPEDIA`	`--nominatim-import-wikipedia`	`false`	Import Wikipedia importance dumps for improved ranking
`NOMINATIM_HTTP_PORT`	`--nominatim-http-port`	`8980`	Host HTTP port exposed via DDEV router
`NOMINATIM_HTTPS_PORT`	`--nominatim-https-port`	`8943`	Host HTTPS port exposed via DDEV router

Data Persistence & Changing Data Extracts

The PostgreSQL database is persisted in a named Docker volume (ddev-<projectname>-nominatim-data).

If you change NOMINATIM_PBF_URL / NOMINATIM_PBF_PATH or want to re-import data from scratch:

Stop DDEV:
```
ddev stop
```

Remove the existing database volume:

docker volume rm ddev-${DDEV_SITENAME}-nominatim-data

Update your .ddev/.env.nominatim configuration:

# Using a URL:
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-url="https://download.geofabrik.de/europe/liechtenstein-latest.osm.pbf"
# Or using a local file:
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-path="data.osm.pbf"

Start DDEV (starts immediately; Nominatim imports in the background):
```
ddev start
```

Hardware Considerations

Small extracts (Monaco, Liechtenstein): ~2 GB RAM, 10–20 GB disk, finishes in minutes.
Medium extracts (countries like Germany, France): 16–32 GB RAM, 50–100 GB fast NVMe disk, can take a few hours.
Full Planet: 64–128 GB+ RAM, 1 TB+ NVMe SSD, takes multiple days.

Credits

Contributed and maintained by @bradley-tran

If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.