Nominatim

Nominatim is an open-source geographic search engine (geocoder).

Try the service in a VM

Install Nix
Arch Linux
Bash
$ pacman --sync --refresh --noconfirm curl git jq nix
Debian
Bash
$ apt install --yes curl git jq nix
Ubuntu
Bash
$ apt install --yes curl git jq nix

Download a configuration file

# default.nix
{
  ngipkgs ? import (fetchTarball "https://github.com/ngi-nix/ngipkgs/tarball/main") { },
}:
ngipkgs.demo-vm (
  { pkgs, ... }:

  {
    # ACME
    security.acme = {
      acceptTerms = true;
      defaults = {
        email = "admin@example.com";
      };
    };

    # Nominatim
    services.nominatim = {
      enable = true;
      hostName = "nominatim";
      ui = {
        config = ''
          Nominatim_Config.Page_Title='Nominatim demo instance';
          Nominatim_Config.Nominatim_API_Endpoint='https://localhost:8443/';
        '';
      };
    };

    environment.systemPackages = [ pkgs.wget ];

    services.nginx.defaultSSLListenPort = 8443;
    networking.firewall.allowedTCPPorts = [ 8443 ];
  }

)

    Download

    
  

Enable binary substituters
Bash
```
$ export NIX_CONFIG='substituters = https://cache.nixos.org/ https://ngi.cachix.org/
trusted-public-keys = cache.nixos.org-1:6nchdd59x431o0gwypbmraurkbj16zpmqfgspcdshjy= ngi.cachix.org-1:n+cal72roc3qqulxihpv+tw5t42whxmmhpragkrsrow='
```
Build and run a virtual machine
Arch Linux, Debian Sid and Ubuntu 25.04
Bash
$ nix-build ./default.nix && ./result
Debian 12 and Ubuntu 24.04/24.10
Bash
$ rev=$(nix-instantiate --eval --attr sources.nixpkgs.rev https://github.com/ngi-nix/ngipkgs/archive/master.tar.gz | jq --raw-output)

$ nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/$rev.tar.gz --packages nix --run "nix-build ./default.nix && ./result"
Usage Instructions
A demo VM for testing Nominatim.
1. First, download some OpenStreetMap data from Geofabrik.de, for example Andorra.
$ cd /tmp $ wget https://download.geofabrik.de/europe/andorra-latest.osm.pbf
1. Import data to Nominatim database
$ sudo -u nominatim
NOMINATIM_DATABASE_WEBUSER=nominatim-api
nominatim import --continue import-from-file --osm-file andorra-latest.osm.pbf
1. Restart Nominatim service
$ sudo systemctl restart nominatim.service
1. Test Nominatim API in terminal
$ curl -k https://localhost:8443/status $ curl -k "https://localhost:8443/search?q=Andorra&format=geojson"
1. Test Nominatim UI in browser
$ open https://localhost:8443

Options

programs.nominatim

programs.nominatim.enable

Whether to enable nominatim.

Type:: boolean
Default:: false

programs.nominatim.package

The nominatim package to use.

Type:: package
Default:: pkgs.nominatim

services.nominatim

services.nominatim.database.apiUser

Postgresql database user with read-only permissions used for Nominatim web API service.

Type:: string
Default:: "nominatim-api"

services.nominatim.database.dbname

Name of the postgresql database.

Type:: string
Default:: "nominatim"

services.nominatim.database.extraConnectionParams

Extra Nominatim database connection parameters.

Format: =;=

See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS.

Type:: null or string
Default:: null

services.nominatim.database.host

Host of the postgresql server. If not set to localhost, Nominatim database and postgresql superuser with appropriate permissions must exist on target host.

Type:: string
Default:: "localhost"

services.nominatim.database.passwordFile

Password file used for Nominatim database connection. Must be readable only for the Nominatim web API user.

The file must be a valid .pgpass file as described in: https://www.postgresql.org/docs/current/libpq-pgpass.html

In most cases, the following will be enough:

*:*:*:*:<password>

Type:: null or absolute path
Default:: null

services.nominatim.database.port

Port of the postgresql database.

Type:: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:: 5432

services.nominatim.database.superUser

Postgresql database superuser used to create Nominatim database and import data. If database.host is set to localhost, a unix user and group of the same name will be automatically created.

Type:: string
Default:: "nominatim"

services.nominatim.enable

Whether to enable nominatim.

Also enables nginx virtual host management. Further nginx configuration can be done by adapting services.nginx.virtualHosts.<name>. See .

Type:: boolean
Default:: false

services.nominatim.hostName

Hostname to use for the nginx vhost.

Type:: string

services.nominatim.package

The nominatim-api package to use.

Type:: package
Default:: pkgs.nominatim-api
Notes:: Missing update script An update script is required for automatically tracking the latest release.

services.nominatim.settings

Nominatim configuration settings. For the list of available configuration options see https://nominatim.org/release-docs/latest/customize/Settings.

Type:: attribute set of string
Default:: { }

services.nominatim.ui.config

Nominatim UI configuration placed to theme/config.theme.js file.

For the list of available configuration options see https://github.com/osm-search/nominatim-ui/blob/master/dist/config.defaults.js.

Type:: null or string
Default:: null

services.nominatim.ui.package

The nominatim-ui package to use.

Type:: package
Default:: pkgs.nominatim-ui
Notes:: Missing update script An update script is required for automatically tracking the latest release.

Examples

Nominatim service with API, UI and CLI support

{ pkgs, ... }:

{
  # ACME
  security.acme = {
    acceptTerms = true;
    defaults = {
      email = "admin@example.com";
    };
  };

  # Nominatim
  services.nominatim = {
    enable = true;
    hostName = "nominatim";
    ui = {
      config = ''
        Nominatim_Config.Page_Title='Nominatim demo instance';
        Nominatim_Config.Nominatim_API_Endpoint='https://localhost:8443/';
      '';
    };
  };

  environment.systemPackages = [ pkgs.wget ];

  services.nginx.defaultSSLListenPort = 8443;
  networking.firewall.allowedTCPPorts = [ 8443 ];
}

    
    
  

This project is funded by NLnet through these subgrants: