Nominatim

https://nominatim.org/release-docs/latest
Admin
Nominatim is a tool to search OpenStreetMap data by name and address, generate synthetic addresses...
Tokens:149,891
Snippets:1,015
Trust Score:9.5
Update:18 hours ago
Show doc for...
Tokens:
Raw
### Install nginx

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs nginx as the web server for proxying.

```bash
sudo apt-get install -y nginx
```

--------------------------------

### Install Apache and enable proxy module

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs Apache and enables the proxy_http module required for proxying.

```bash
sudo apt-get install -y apache2
sudo a2enmod proxy_http
```

--------------------------------

### Install locale with dpkg-reconfigure

Source: https://nominatim.org/release-docs/latest/admin/Faq/

Installs or configures the locale on Ubuntu.

```bash
dpkg-reconfigure locales
```

--------------------------------

### Install nominatim-api package from source

Source: https://nominatim.org/release-docs/latest/admin/Deployment-Python/

Installs the 'nominatim-api' package into the virtual environment from the source tree.

```bash
cd Nominatim
/srv/nominatim-venv/bin/pip install packaging/nominatim-api
```

--------------------------------

### Install Python frontend packages

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs falcon, uvicorn, gunicorn, and nominatim-api for running the API as a webservice.

```bash
$USERHOME/nominatim-venv/bin/pip install falcon uvicorn gunicorn nominatim-api
```

--------------------------------

### Build and install osm2pgsql from source

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-22/

Ubuntu's default osm2pgsql is too old (needs >= 1.8). This clones the source, builds it with cmake, and installs it.

```bash
cd $USERHOME
git clone https://github.com/osm2pgsql-dev/osm2pgsql
mkdir osm2pgsql-build
cd osm2pgsql-build
cmake ../osm2pgsql
make
sudo make install
```

--------------------------------

### Install Nominatim from PyPI

Source: https://nominatim.org/release-docs/latest/admin/Installation/

Installs the latest Nominatim release using pip. Requires osm2pgsql, PostgreSQL/PostGIS, and libICU with header files to be installed beforehand.

```bash
pip install nominatim-db nominatim-api
```

--------------------------------

### Install psycopg binary

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs the faster binary version of psycopg into the virtual environment.

```bash
$USERHOME/nominatim-venv/bin/pip install psycopg[binary]
```

--------------------------------

### Start local web server for nominatim-ui

Source: https://nominatim.org/release-docs/latest/admin/Setup-Nominatim-UI/

Starts a Python HTTP server in the dist directory to serve the UI locally. The website will be available at http://localhost:8765.

```bash
cd nominatim-ui/dist
python3 -m http.server 8765
```

--------------------------------

### Install nominatim-api from PyPI

Source: https://nominatim.org/release-docs/latest/library/Getting-Started/

Installs the latest released version of the nominatim-api package from PyPI.

```bash
pip install nominatim-api
```

--------------------------------

### Install SQLite and Spatialite prerequisites on Ubuntu/Debian

Source: https://nominatim.org/release-docs/latest/customize/SQLite/

Installs SQLite, the Spatialite module, and libspatialite7 required for SQLite support. Run this before using SQLite features.

```bash
sudo apt install sqlite3 libsqlite3-mod-spatialite libspatialite7
```

--------------------------------

### Install Vagrant and libvirt packages for VM development

Source: https://nominatim.org/release-docs/latest/develop/Development-Environment/

Install packages needed to run Nominatim in a VM via Vagrant with the libvirt provider on Ubuntu.

```bash
sudo apt install vagrant vagrant-libvirt libvirt-daemon nfs-kernel-server
```

--------------------------------

### Andorra country settings example

Source: https://nominatim.org/release-docs/latest/customize/Country-Settings/

Example configuration for Andorra in settings/country_settings.yaml. Shows the partition, languages, names (via !include), and postcode pattern with output.

```yaml
    partition: 35
    languages: ca
    names: !include country-names/ad.yaml
    postcode:
      pattern: "(ddd)"
      output: AD\1
```

--------------------------------

### Start a custom style with flex-base

Source: https://nominatim.org/release-docs/latest/customize/Import-Styles/

Every custom style must include the flex-base module to ensure correct table creation. This is the required starting point for any custom style.

```lua
local flex = require('flex-base')
```

--------------------------------

### set_unused_handling example

Source: https://nominatim.org/release-docs/latest/customize/Import-Styles/

Moves all remaining tags except those starting with tiger: to extratags. Note that tiger tags cannot be deleted with set_prefilters() because that would remove tiger:county before address tags are processed.

```lua
local flex = require('import-full')

flex.set_address_tags{
    main = {'addr:housenumber'},
    extra = {'addr:*', 'tiger:county'}
}
flex.set_unused_handling{delete_keys = {'tiger:*'}}
```

--------------------------------

### Serve documentation locally with make serve-doc

Source: https://nominatim.org/release-docs/latest/develop/Development-Environment/

Starts a local webserver for testing documentation. The output shows the server serving on http://127.0.0.1:8000 and watching for changes.

```bash
build> make serve-doc
[server:296] Serving on http://127.0.0.1:8000
[handlers:62] Start watching changes
```

--------------------------------

### Print number of rows in placex table

Source: https://nominatim.org/release-docs/latest/library/Low-Level-DB-Access/

Example that prints how many places are available in the placex table using NominatimAPIAsync and SQLAlchemy. It uses the begin() context manager to get a SearchConnection and executes a scalar count query. Note that low-level connections are read-only and the database layout may change without notice.

```python
import asyncio
import sqlalchemy as sa
from nominatim_api import NominatimAPIAsync

async def print_table_size():
    api = NominatimAPIAsync()

    async with api.begin() as conn:
        cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
        print(f'placex table has {cnt} rows.')

asyncio.run(print_table_size())
```

--------------------------------

### Start Nominatim import

Source: https://nominatim.org/release-docs/latest/admin/Import/

Run the import command from the project directory with the OSM data file. Redirect output to setup.log for review.

```bash
nominatim import --osm-file <data file> 2>&1 | tee setup.log
```

--------------------------------

### Install Nominatim into virtual environment

Source: https://nominatim.org/release-docs/latest/admin/Installation/

Installs Nominatim from the source tree into the virtual environment using pip. The command installs the db and api packages.

```bash
/srv/nominatim-venv/bin/pip install packaging/nominatim-{db,api}
```

--------------------------------

### NominatimAPIAsync.setup_database

Source: https://nominatim.org/release-docs/latest/library/NominatimAPI/

Sets up the SQL engine and connections. This function is implicitly called when the database is accessed for the first time, but can be called explicitly to avoid delay on the first call.

```APIDOC
## NominatimAPIAsync.setup_database

### Description
Set up the SQL engine and connections. This function will be implicitly called when the database is accessed for the first time. You may also call it explicitly to avoid that the first call is delayed by the setup.

### Method
async function

### Signature
`async setup_database()`

### Parameters
None
```

--------------------------------

### Setup website configuration

Source: https://nominatim.org/release-docs/latest/admin/Migration/

Command to create the website configuration file after updating, as part of switching to dotenv.

```shell
./utils/setup.php --setup-website
```

--------------------------------

### Test search query

Source: https://nominatim.org/release-docs/latest/admin/Import/

Execute a simple search query on the command line to test the installation.

```bash
nominatim search --query Berlin
```

--------------------------------

### Install Nominatim via pip

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs the nominatim-db package into the virtual environment.

```bash
$USERHOME/nominatim-venv/bin/pip install nominatim-db
```

--------------------------------

### Run initial import

Source: https://nominatim.org/release-docs/latest/admin/Advanced-Installations/

Run the import_multiple_regions.sh script from the project directory to start the initial import.

```bash
bash import_multiple_regions.sh
```

--------------------------------

### Prepare database with superuser rights

Source: https://nominatim.org/release-docs/latest/admin/Advanced-Installations/

Run the database preparation step with a superuser account. Replace 'dbadmin' and 'nominatim' with your actual database user and database name.

```bash
NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim;user=dbadmin" nominatim import --prepare-database
```

--------------------------------

### Country without postcodes example

Source: https://nominatim.org/release-docs/latest/customize/Country-Settings/

Example for a country with no official postcodes, setting postcode to 'no'.

```yaml
ae:
    postcode: no
```

--------------------------------

### Create and populate Python virtual environment

Source: https://nominatim.org/release-docs/latest/develop/Development-Environment/

Create a virtual environment and install all Python packages needed for development, testing, and documentation.

```bash
virtualenv ~/nominatim-dev-venv
```

```bash
~/nominatim-dev-venv/bin/pip install\
    psutil 'psycopg[binary]' PyICU SQLAlchemy \
    python-dotenv jinja2 pyYAML \
    mkdocs 'mkdocstrings[python]' mkdocs-gen-files mkdocs-material \
    pytest pytest-asyncio pytest-bdd flake8 \
    types-jinja2 types-markupsafe types-psutil types-psycopg2 \
    types-pygments types-pyyaml types-requests types-ujson \
    types-urllib3 typing-extensions gunicorn falcon starlette \
    uvicorn mypy osmium aiosqlite mwparserfromhell
```

--------------------------------

### Install system packages for Nominatim development

Source: https://nominatim.org/release-docs/latest/develop/Development-Environment/

Install system dependencies required for building and running Nominatim on Ubuntu/Debian.

```bash
sudo apt install build-essential libsqlite3-mod-spatialite osm2pgsql \
                 postgresql-postgis postgresql-postgis-scripts \
                 pkg-config libicu-dev virtualenv
```

--------------------------------

### Install Falcon and gunicorn packages

Source: https://nominatim.org/release-docs/latest/admin/Deployment-Python/

Adds the Falcon web framework and gunicorn HTTP server to the virtual environment.

```bash
/srv/nominatim-venv/bin/pip install falcon gunicorn
```

--------------------------------

### Install Nominatim dependencies

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-24/

Installs all packages needed for Nominatim, including osm2pgsql, PostgreSQL with PostGIS, and build tools.

```bash
sudo apt-get install -y osm2pgsql postgresql-postgis postgresql-postgis-scripts \
                        pkg-config libicu-dev virtualenv
```

--------------------------------

### Install aiosqlite Python package in virtual environment

Source: https://nominatim.org/release-docs/latest/customize/SQLite/

Installs the aiosqlite package into the Nominatim virtual environment, a prerequisite for SQLite support.

```bash
/srv/nominatim-venv/bin/pip install aiosqlite
```

--------------------------------

### Initialize replication process

Source: https://nominatim.org/release-docs/latest/admin/Update/

Run 'nominatim replication --init' to set up the update process. It outputs the date where updates will start; recheck that date. Rerun this command whenever the replication service is changed.

```bash
nominatim replication --init
```

--------------------------------

### Install Pyosmium via pip

Source: https://nominatim.org/release-docs/latest/admin/Update/

Install the Pyosmium library using pip. Run this command as the same user who will later run the updates.

```bash
pip3 install --user osmium
```

--------------------------------

### Create project directory

Source: https://nominatim.org/release-docs/latest/admin/Import/

Creates a project directory for the Nominatim setup and changes into it. Run these commands from a location separate from the Nominatim software.

```bash
mkdir ~/nominatim-project
cd ~/nominatim-project
```

--------------------------------

### Install Nominatim dependencies

Source: https://nominatim.org/release-docs/latest/admin/Install-on-Ubuntu-22/

Installs all required packages for Nominatim on Ubuntu 22.04, including build tools, libraries, PostgreSQL with PostGIS, and virtualenv.

```bash
sudo apt-get install -y build-essential cmake g++ libboost-dev libboost-system-dev \
                    libboost-filesystem-dev libexpat1-dev zlib1g-dev \
                    libbz2-dev libpq-dev liblua5.3-dev lua5.3 lua-dkjson \
                    nlohmann-json3-dev postgresql-14-postgis-3 \
                    postgresql-contrib-14 postgresql-14-postgis-3-scripts \
                    libicu-dev virtualenv git
```

--------------------------------

### Configure replication source in .env

Source: https://nominatim.org/release-docs/latest/admin/Update/

Example .env settings to use daily country extracts diffs for Ireland from Geofabrik. Sets the replication URL, update interval (86400 seconds), and recheck interval (900 seconds).

```bash
# base URL of the replication service
NOMINATIM_REPLICATION_URL="https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates"
# How often upstream publishes diffs (in seconds)
NOMINATIM_REPLICATION_UPDATE_INTERVAL=86400
# How long to sleep if no update found yet (in seconds)
NOMINATIM_REPLICATION_RECHECK_INTERVAL=900
```
Tokens:
Raw