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/Trixie and Ubuntu 25.04
Bash
$ nix-build ./default.nix && ./result
Ubuntu 24.04
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](https://download.geofabrik.de/), for example Andorra. $ cd /tmp $ wget https://download.geofabrik.de/europe/andorra-latest.osm.pbf 2. 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 3. Restart Nominatim service $ sudo systemctl restart nominatim.service 4. Test Nominatim API in terminal $ curl -k https://localhost:8443/status $ curl -k "https://localhost:8443/search?q=Andorra&format=geojson" 5. Test Nominatim UI in browser $ open https://localhost:8443

Options

programs.nominatim

: Whether to enable nominatim.

Type:

boolean

Default:

false
: The nominatim package to use.

Type:

package

Default:

pkgs.nominatim

services.nominatim

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

Type:

string

Default:

"nominatim-api"
: Name of the postgresql database.

Type:

string

Default:

"nominatim"
: Extra Nominatim database connection parameters.

Format: =;=

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

Type:

null or string

Default:

null
: 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"
: 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
: Port of the postgresql database.

Type:

16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

5432
: 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"
: 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
: Hostname to use for the nginx vhost.

Type:

string
: 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.
: 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:

{ }
: 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
: 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: