Nominatim Documentation

Technical Documentation: osm-search/Nominatim

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Nominatim

Nominatim (from the Latin, 'by name') is a tool to search OpenStreetMap data
by name and address (geocoding) and to generate synthetic addresses of
OSM points (reverse geocoding). An instance with up-to-date data can be found
at https://nominatim.openstreetmap.org. Nominatim is also used as one of the
sources for the Search box on the OpenStreetMap home page.

Documentation

The documentation of the latest development version is in the
docs/ subdirectory. A HTML version can be found at
https://nominatim.org/release-docs/develop/ .

Installation

The latest stable release can be downloaded from https://nominatim.org.
There you can also find installation instructions for the release, as well as an extensive Troubleshooting/FAQ section.

Detailed installation instructions for current master
can be found at nominatim.org as well.

A quick summary of the necessary steps:

1. Clone this git repository and download the country grid

   text Copy

   git clone https://github.com/osm-search/Nominatim.git
    wget -O Nominatim/data/country_osm_grid.sql.gz https://nominatim.org/data/country_grid.sql.gz

2. Create a Python virtualenv and install the packages:

   text Copy

   python3 -m venv nominatim-venv
    ./nominatim-venv/bin/pip install packaging/nominatim-{api,db}

3. Create a project directory, get OSM data and import:

   text Copy

   mkdir nominatim-project
    cd nominatim-project
    ../nominatim-venv/bin/nominatim import --osm-file <your planet file> 2>&1 | tee setup.log

4. Start the webserver:

   text Copy

   ./nominatim-venv/bin/pip install uvicorn falcon
    ../nominatim-venv/bin/nominatim serve

License

The Python source code is available under a GPL license version 3 or later.
The Lua configuration files for osm2pgsql are released under the
Apache License, Version 2.0. All other files are under a GPLv2 license.

Contributing

Contributions, bug reports and pull requests are welcome. When reporting a
bug, please use one of the
issue templates
and make sure to provide all the information requested. If you are not
sure if you have really found a bug, please ask for help in the forums
first (see 'Questions' below).

For details on contributing, have a look at the
contribution guide.

Questions and help

If you have questions about search results and the OpenStreetMap data
used in the search, use the OSM Forum.

For questions, community help and discussions around the software and
your own installation of Nominatim, use the
Github discussions forum.

Overview (`packaging/nominatim-api/README.md`) Copy Section

Nominatim - Frontend Library

Nominatim is a tool to search OpenStreetMap data
by name and address (geocoding) and to generate synthetic addresses of
OSM points (reverse geocoding).

This module implements the library for searching a Nominatim database
imported with the nominatim-db package.

Installation Copy Chapter

To install the Nominatim API from pypi, run:

pip install nominatim-api

Running a Nominatim server Copy Chapter

You need Falcon or Starlette to run Nominatim as a service, as well as
an ASGI-capable server like uvicorn. To install them from pypi run:

pip install falcon uvicorn

You need to have a Nominatim database imported with the 'nominatim-db'
package. Go to the project directory, then run uvicorn as:

uvicorn --factory nominatim_api.server.falcon.server:run_wsgi

Documentation Copy Chapter

The full documentation for the Nominatim library can be found at:
https://nominatim.org/release-docs/latest/library/Getting-Started/

The v1 API of the server is documented at:
https://nominatim.org/release-docs/latest/api/Overview/

License Copy Chapter

The source code is available under a GPLv3 license.

Overview (`packaging/nominatim-db/README.md`) Copy Section

Nominatim - DB Backend

Nominatim is a tool to search OpenStreetMap data
by name and address (geocoding) and to generate synthetic addresses of
OSM points (reverse geocoding).

This module implements the database backend for Nominatim and the
command-line tool for importing and maintaining the database.

Installation Copy Chapter

Prerequisites Copy Section

Nominatim requires osm2pgsql (>=1.8) for reading
OSM data and PostgreSQL (>=9.6) to store the data.

On Ubuntu (>=23.04) and Debian (when using backports), you can install them with:

sudo apt-get install osm2pgsql postgresql-postgis

Installation from pypi Copy Section

To install Nominatim from pypi, run:

pip install nominatim-db

Quick start Copy Chapter

First create a project directory for your new Nominatim database, which
is the space for additional configuration and customization:

mkdir nominatim-project

Make sure you run all nominatim commands from within the project directory:

cd nominatim-project

Download an appropriate data extract, for example from
Geofabrik and import the file:

nominatim import --osm-file <downlaoded-osm-data.pbf>

You will need to install the nominatim-api
package to query the database.

Documentation Copy Chapter

A HTML version of the documentation can be found at
https://nominatim.org/release-docs/latest/ .

License Copy Chapter

The source code is available under a GPLv3 license.

Index (`docs/index.md`) Copy Section

Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and
address and to generate synthetic addresses of OSM points (reverse geocoding).
It has also limited capability to search features by their type
(pubs, hotels, churches, etc).

This guide comes in five parts:

• API reference for users of Nominatim
• Administration Guide for those who want
  to install their own Nominatim server
• Customization Guide for those who want to
  adapt their own installation to their special requirements
• Library Guide for Python developers who
  want to use Nominatim as a library in their project
• Developer's Guide for developers of the software

Api Overview (`docs/api/Overview.md`) Copy Section

This section describes the API V1 of the Nominatim web service. The
service offers the following endpoints:

• /search - search OSM objects by name or type
• /reverse - search OSM object by their location
• /lookup - look up address details for OSM objects by their ID
• /status - query the status of the server
• /deletable - list objects that have been deleted in OSM but are held
  back in Nominatim in case the deletion was accidental
• /polygons - list of broken polygons detected by Nominatim
• /details - show internal details for an object (for debugging only)

Customize Overview (`docs/customize/Overview.md`) Copy Section

Nominatim comes with a predefined set of configuration options that should
work for most standard installations. If you have special requirements, there
are many places where the configuration can be adapted. This chapter describes
the following configurable parts:

• Global Settings has a detailed description of all parameters that
  can be set in your local .env configuration
• Import styles explains how to write your own import style
  in order to control what kind of OSM data will be imported
• API Result Formatting shows how to change the
  output of the Nominatim API
• Place ranking describes the configuration around classifing
  places in terms of their importance and their role in an address
• Tokenizers describes the configuration of the module
  responsible for analysing and indexing names
• Special Phrases are common nouns or phrases that
  can be used in search to identify a class of places

There are also guides for adding the following external data:

• US house numbers from the TIGER dataset
• External postcodes

Develop Overview (`docs/develop/overview.md`) Copy Section

Basic Architecture

Nominatim provides geocoding based on OpenStreetMap data. It uses a PostgreSQL
database as a backend for storing the data.

There are three basic parts to Nominatim's architecture: the data import,
the address computation and the search frontend.

The data import stage reads the raw OSM data and extracts all information
that is useful for geocoding. This part is done by osm2pgsql, the same tool
that can also be used to import a rendering database. It uses the special
flex output style defined in the directory /lib-lua. The result of
the import can be found in the database table place.

The address computation or indexing stage takes the data from place
and adds additional information needed for geocoding. It ranks the places by
importance, links objects that belong together and computes addresses and
the search index. Most of this work is done in PL/pgSQL via database triggers
and can be found in the files in the sql/functions/ directory.

The search frontend implements the actual API. It takes search
and reverse geocoding queries from the user, looks up the data and
returns the results in the requested format. This part is located in the
nominatim-api package. The source code can be found in src/nominatim_api.

Result filters and the rounds of a forward search Copy Chapter

A forward search is not a single database query. The frontend derives the
possible interpretations of the query, orders them by penalty and runs them in
rounds until it has collected enough good results. Every round that produces a
result also restricts the ranks that the following rounds may still return, so
the search usually stops long before all interpretations have been tried.

The result filters of the search API (include, exclude, countrycodes
and layer) are applied within these queries. Dropping an early result
therefore lets later, higher-penalty rounds run that would otherwise never
have been reached. As a consequence a filtered query may return more results
than the unfiltered one, and results that the unfiltered query never showed.
That is expected behaviour.

Library Getting Started (`docs/library/Getting-Started.md`) Copy Section

Getting Started

The Nominatim search frontend is implemented as a Python library and can as
such directly be used in Python scripts and applications. You don't need to
set up a web frontend and access it through HTTP calls. The library gives
direct access to the Nominatim database through similar search functions as
offered by the web API. In addition, it will give you a more complete and
detailed view on the search objects stored in the database.

!!! warning

The Nominatim library is used for accessing a local Nominatim database.
It is not meant to be used against web services of Nominatim like the
one on https://nominatim.openstreetmap.org. If you need a Python library
to access these web services, have a look at
[GeoPy](https://geopy.readthedocs.io). Don't forget to consult the
usage policy of the service you want to use before accessing such
a web service.

Installation Copy Chapter

To use the Nominatim library, you need access to a local Nominatim database.
Follow the installation and
import instructions to set up your database.

The Nominatim frontend library is contained in the Python package nominatim-api.
You can install the latest released version directly from pip:

pip install nominatim-api

To install the package from the source tree directly, run:

pip install packaging/nominatim-api

Usually you would want to run this in a virtual environment.

A simple search example Copy Chapter

To query the Nominatim database you need to first set up a connection. This
is done by creating an Nominatim API object. This object exposes all the
search functions of Nominatim that are also known from its web API.

This code snippet implements a simple search for the town of 'Brugge':

!!! example
=== "NominatimAPIAsync"
``` python
import asyncio

import nominatim_api as napi

    async def search(query):
        async with napi.NominatimAPIAsync() as api:
            return await api.search(query)

    results = asyncio.run(search('Brugge'))
    if not results:
        print('Cannot find Brugge')
    else:
        print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
    ```

=== "NominatimAPI"
    ``` python
    import nominatim_api as napi

    with napi.NominatimAPI() as api:
        results = api.search('Brugge')

    if not results:
        print('Cannot find Brugge')
    else:
        print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
    ```

The Nominatim library is designed around
asyncio. NominatimAPIAsync
provides you with an interface of coroutines.
If you have many requests to make, coroutines can speed up your applications
significantly.

For smaller scripts there is also a synchronous wrapper around the API. By
using NominatimAPI, you get exactly the same interface using classic functions.

The examples in this chapter will always show-case both
implementations. The documentation itself will usually refer only to
'Nominatim API class' when both flavours are meant. If a functionality is
available only for the synchronous or asynchronous version, this will be
explicitly mentioned.

Defining which database to use Copy Chapter

The Configuration
section explains how Nominatim is configured using the
dotenv library.
The same configuration mechanism is used with the
Nominatim API library. You should therefore be sure you are familiar with
the section.

There are three different ways, how configuration options can be set for
a 'Nominatim API class'. When you have set up your Nominatim database, you
have normally created a project directory
which stores the various configuration and customization files that Nominatim
needs. You may pass the location of the project directory to your
'Nominatim API class' constructor and it will read the .env file in the
directory and set the configuration accordingly. Here is the simple search
example, using the configuration from a pre-defined project directory in
/srv/nominatim-project:

!!! example
=== "NominatimAPIAsync"
``` python
import asyncio

import nominatim_api as napi

    async def search(query):
        async with napi.NominatimAPIAsync('/srv/nominatim-project') as api:
            return await api.search(query)

    results = asyncio.run(search('Brugge'))
    if not results:
        print('Cannot find Brugge')
    else:
        print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
    ```

=== "NominatimAPI"
    ``` python
    import nominatim_api as napi

    with napi.NominatimAPI('/srv/nominatim-project') as api:
        results = api.search('Brugge')

    if not results:
        print('Cannot find Brugge')
    else:
        print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
    ```

You may also configure Nominatim by setting environment variables.
Normally Nominatim will check the operating system environment. Lets
say you want to look up 'Brugge' in the special database named 'belgium' instead of the
standard 'nominatim' database. You can run the example script above like this:

NOMINATIM_DATABASE_DSN=pgsql:dbname=belgium python3 example.py

The third option to configure the library is to hand in the configuration
parameters into the 'Nominatim API class'. Changing the database would look
like this:

!!! example
=== "NominatimAPIAsync"
``` python
import asyncio
import nominatim_api as napi

config_params = {
        'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
    }

    async def search(query):
        async with napi.NominatimAPIAsync(environ=config_params) as api:
            return await api.search(query)

    results = asyncio.run(search('Brugge'))
    ```

=== "NominatimAPI"
    ``` python
    import nominatim_api as napi

    config_params = {
        'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
    }

    with napi.NominatimAPI(environ=config_params) as api:
        results = api.search('Brugge')
    ```

When the environ parameter is given, then only configuration variables
from this dictionary will be used. The operating system's environment
variables will be ignored.

Presenting results to humans Copy Chapter

All search functions return full result objects from the database. Such a
result object contains lots of details: names, address information, OSM tags etc.
This gives you lots of flexibility what to do with the results.

One of the most common things to get is some kind of human-readable label
that describes the result in a compact form. Usually this would be the name
of the object and some parts of the address to explain where in the world
it is. To create such a label, you need two things:

• the address details of the place
• all names for the label adapted to the language you wish to use for display

Again searching for 'Brugge', this time with a nicely formatted result:

!!! example
=== "NominatimAPIAsync"
``` python
import asyncio

import nominatim_api as napi

    async def search(query):
        async with napi.NominatimAPIAsync() as api:
            return await api.search(query, address_details=True)

    results = asyncio.run(search('Brugge'))

    locale = napi.Locales(['fr', 'en'])
    for i, result in enumerate(results):
        address_parts = result.address_rows.localize(locale)
        print(f"{i + 1}. {', '.join(address_parts)}")
    ```

=== "NominatimAPI"
    ``` python
    import nominatim_api as napi

    with napi.NominatimAPI() as api:
        results = api.search('Brugge', address_details=True)

    locale = napi.Locales(['fr', 'en'])
    for i, result in enumerate(results):
        address_parts = result.address_rows.localize(locale)
        print(f"{i + 1}. {', '.join(address_parts)}")
    ```

To request information about the address of a result, add the optional
parameter 'address_details' to your search:

>>> results = api.search('Brugge', address_details=True)

An additional field address_rows will set in results that are returned.
It contains a list of all places that make up the address of the place. For
simplicity, this includes name and house number of the place itself. With
the names in this list it is possible to create a human-readable description
of the result. To do that, you first need to decide in which language the
results should be presented. As with the names in the result itself, the
places in address_rows contain all possible name translation for each row.

The library has a helper class Locales which helps extracting a name of a
place in the preferred language. It takes a single parameter with a list
of language codes in the order of preference. So

locale = napi.Locales(['fr', 'en'])

creates a helper class that returns the name preferably in French. If that is
not possible, it tries English and eventually falls back to the default name
or ref.

The Locales object can be applied to a name dictionary to return the best-matching
name out of it:

>>> print(locale.display_name(results[0].names))
'Brugges'

The address_row field has a helper function to compute the display name for each Address Line
component based on its local_name field. This is then utilized by the overall result object,
which has a helper function to apply the function to all its ‘address_row’ members and saves
the result in the locale_name field.

However, in order to set this local_name field in a preferred language, you must use the Locales
object which contains the function localize_results, which explicitly sets each local_name field.

>>> Locales().localize_results(results)
>>> address_parts = results[0].address_rows
>>> print(', '.join(address_parts))
Bruges, Flandre-Occidentale, Flandre, Belgique

This is a fairly simple way to create a human-readable description. The
place information in address_rows contains further information about each
place. For example, which OSM admin_level was used, what category the place
belongs to or what rank Nominatim has assigned. Use this to adapt the output
to local address formats.

For more information on address rows, see
detailed address description.

Admin Advanced Installations (`docs/admin/Advanced-Installations.md`) Copy Section

Advanced installations

This page contains instructions for setting up multiple countries in
your Nominatim database. It is assumed that you have already successfully
installed the Nominatim software itself, if not return to the
installation page.

Importing with a database user without superuser rights Copy Chapter

Nominatim usually creates its own PostgreSQL database at the beginning of the
import process. This makes usage easier for the user but means that the
database user doing the import needs the appropriate rights.

If you prefer to run the import with a database user with limited rights,
you can do so by changing the import process as follows:

1. Run the command for database preparation with a database user with
   superuser rights. For example, to use a db user 'dbadmin' for a
   database 'nominatim', execute:

   text Copy

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

2. Grant the import user the right to create tables. For example, foe user 'import-user':

   text Copy

   psql -d nominatim -c 'GRANT CREATE ON SCHEMA public TO "import-user"'

3. Now run the reminder of the import with the import user:

   text Copy

   NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim;user=import-user" nominatim import --continue import-from-file --osm-file file.pbf

Importing multiple regions (without updates) Copy Chapter

To import multiple regions in your database you can simply give multiple
OSM files to the import command:

nominatim import --osm-file file1.pbf --osm-file file2.pbf

If you already have imported a file and want to add another one, you can
use the add-data function to import the additional data as follows:

nominatim add-data --file <FILE>
nominatim refresh --postcodes
nominatim index -j <NUMBER OF THREADS>

Please note that adding additional data is always significantly slower than
the original import.

Importing multiple regions (with updates) Copy Chapter

If you want to import multiple regions and be able to keep them up-to-date
with updates, then you can use the scripts provided in the utils directory.

These scripts will set up an update directory in your project directory,
which has the following structure:

update
 ├── europe
 │    ├── andorra
 │    │    └── sequence.state
 │    └── monaco
 │         └── sequence.state
 └── tmp
      └── europe
           ├── andorra-latest.osm.pbf
           └── monaco-latest.osm.pbf

The sequence.state files contain the sequence ID for each region. They will
be used by pyosmium to get updates. The tmp folder is used for import dump and
can be deleted once the import is complete.

Setting up multiple regions Copy Section

Create a project directory as described for the
simple import. If necessary,
you can also add an .env configuration with customized options. In particular,
you need to make sure that NOMINATIM_REPLICATION_UPDATE_INTERVAL and
NOMINATIM_REPLICATION_RECHECK_INTERVAL are set according to the update
interval of the extract server you use.

Copy the scripts utils/import_multiple_regions.sh and utils/update_database.sh
into the project directory.

Now customize both files as per your requirements

1. List of countries. e.g.

   text Copy

   COUNTRIES="europe/monaco europe/andorra"

2. URL to the service providing the extracts and updates. eg:

   text Copy

   BASEURL="https://download.geofabrik.de"
    DOWNCOUNTRYPOSTFIX="-latest.osm.pbf"

3. Followup in the update script can be set according to your installation.
   E.g. for Photon,

   text Copy

   FOLLOWUP="curl http://localhost:2322/nominatim-update"

   will handle the indexing.

To start the initial import, change into the project directory and run

bash import_multiple_regions.sh

Updating the database Copy Section

Change into the project directory and run the following command:

bash update_database.sh

This will get diffs from the replication server, import diffs and index
the database. The default replication server in the
script (Geofabrik) provides daily updates.

Using an external PostgreSQL database Copy Chapter

You can install Nominatim using a database that runs on a different server.
Simply point the configuration variable NOMINATIM_DATABASE_DSN to the
server and follow the standard import documentation.

The import will be faster, if the import is run directly from the database
machine. You can easily switch to a different machine for the query frontend
after the import.

Moving the database to another machine Copy Chapter

For some configurations it may be useful to run the import on one machine, then
move the database to another machine and run the Nominatim service from there.
For example, you might want to use a large machine to be able to run the import
quickly but only want a smaller machine for production because there is not so
much load. Or you might want to do the import once and then replicate the
database to many machines.

The important thing to keep in mind when transferring the Nominatim installation
is that you need to transfer the database and the project directory. Both
parts are essential for your installation.

The Nominatim database can be transferred using the pg_dump/pg_restore tool.
Make sure to use the same version of PostgreSQL and PostGIS on source and
target machine.

!!! note
Before creating a dump of your Nominatim database, consider running
nominatim freeze first. Your database looses the ability to receive further
data updates but the resulting database is only about a third of the size
of a full database.

Next install nominatim-api on the target machine by following the standard
installation instructions. Again, make sure to use the same version as the
source machine.

Create a project directory on your destination machine and set up the .env
file to match the configuration on the source machine. That's all.

Admin Deployment Python (`docs/admin/Deployment-Python.md`) Copy Section

Deploying the Nominatim Python frontend

Nominatim can be run as a Python-based
ASGI web application. You have the
choice between Falcon
and Starlette as the ASGI framework.

This section gives a quick overview on how to configure Nginx to serve
Nominatim. Please refer to the documentation of
Nginx for background information on how
to configure it.

Installing the required packages Copy Section

!!! warning
ASGI support in gunicorn requires at least version 25.0. If you need
to work with an older version of gunicorn, please refer to
older Nominatim deployment documentation
to learn how to run gunicorn with uvicorn.

The Nominatim frontend is best run from its own virtual environment. If
you have already created one for the database backend during the
installation, you can use that. Otherwise
create one now with:

sudo apt-get install virtualenv
virtualenv /srv/nominatim-venv

The Nominatim frontend is contained in the 'nominatim-api' package. To
install directly from the source tree run:

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

The recommended way to deploy a Python ASGI application is to run
the gunicorn HTTP server. We use
Falcon here as the web framework.

Add the necessary packages to your virtual environment:

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

Setting up Nominatim as a systemd job Copy Section

!!! Note
These instructions assume your Nominatim project directory is
located in /srv/nominatim-project. If you have put it somewhere else,
you need to adjust the commands and configuration accordingly.

Next you need to set up the service that runs the Nominatim frontend. This is
easiest done with a systemd job.

First you need to tell systemd to create a socket file to be used by
gunicorn. Create the following file /etc/systemd/system/nominatim.socket:

[Unit]
Description=Gunicorn socket for Nominatim

[Socket]
ListenStream=/run/nominatim.sock
SocketUser=www-data

[Install]
WantedBy=multi-user.target

Now you can add the systemd service for Nominatim itself.
Create the following file /etc/systemd/system/nominatim.service:

[Unit]
Description=Nominatim running as a gunicorn application
After=network.target
Requires=nominatim.socket

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/srv/nominatim-project
ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 --worker-class asgi --protocol uwsgi --worker-connections 1000 "nominatim_api.server.falcon.server:run_wsgi()"
ExecReload=/bin/kill -s HUP $MAINPID
PrivateTmp=true
TimeoutStopSec=5
KillMode=mixed

[Install]
WantedBy=multi-user.target

This sets up gunicorn with 4 workers (-w 4 in ExecStart). Each worker runs
its own Python process using
NOMINATIM_API_POOL_SIZE
connections to the database to serve requests in parallel. The parameter
--worker-connections restricts how many requests gunicorn will queue for
each worker. This can help distribute work better when the server is under
high load.

Make the new services known to systemd and start it:

sudo systemctl daemon-reload
sudo systemctl enable nominatim.socket
sudo systemctl start nominatim.socket
sudo systemctl enable nominatim.service
sudo systemctl start nominatim.service

This sets the service up so that Nominatim is automatically started
on reboot.

Configuring nginx Copy Section

To make the service available to the world, you need to proxy it through
nginx. We use the binary uwsgi protocol to speed up communication
between nginx and gunicorn. Add the following definition to the default
configuration:

upstream nominatim_service {
  server unix:/run/nominatim.sock fail_timeout=0;
}

server {
    listen 80;
    listen [::]:80;

    root /var/www/html;
    index /search;

    location / {
        uwsgi_pass nominatim_service;
        include uwsgi_params;
    }
}

Reload nginx with

sudo systemctl reload nginx

and you should be able to see the status of your server under
http://localhost/status.

Admin Faq (`docs/admin/Faq.md`) Copy Section

Troubleshooting Nominatim Installations

Installation Issues Copy Chapter

Can a stopped/killed import process be resumed? Copy Section

"I accidentally killed the import process after it has been running for many hours. Can it be resumed?"

It is possible if the import already got to the indexing stage.
Check the last line of output that was logged before the process
was killed. If it looks like this:

Done 844 in 13 @ 64.923080 per second - Rank 26 ETA (seconds): 7.886255

then you can resume with the following command:

nominatim import --continue indexing

If the reported rank is 26 or higher, you can also safely add --index-noanalyse.

PostgreSQL crashed "invalid page in block" Copy Section

Usually serious problem, can be a hardware issue, not all data written to disc
for example. Check PostgreSQL log file and search PostgreSQL issues/mailing
list for hints.

If it happened during index creation you can try rerunning the step with

nominatim import --continue indexing

Otherwise it's best to start the full setup from the beginning.

I see the error: "ERROR: mmap (remap) failed" Copy Section

This may be a simple out-of-memory error. Try reducing the memory used
for --osm2pgsql-cache. Also make sure that overcommitting memory is
allowed: cat /proc/sys/vm/overcommit_memory should print 0 or 1.

If you are using a flatnode file, then it may also be that the underlying
filesystem does not fully support 'mmap'. A notable candidate is virtualbox's
vboxfs.

nominatim UPDATE failed: ERROR: buffer 179261 is not owned by resource owner Portal Copy Section

Several users reported this
during the initial import of the database. It's
something PostgreSQL internal Nominatim doesn't control. And PostgreSQL forums
suggest it's threading related but definitely some kind of crash of a process.
Users reported either rebooting the server, different hardware or just trying
the import again worked.

The website shows: "Could not get word tokens" Copy Section

The server cannot access your database. Add &debug=1 to your URL
to get the full error message.

Website reports "DB Error: insufficient permissions" Copy Section

The user the webserver, e.g. Apache, runs under needs to have access to the
Nominatim database. You can find the user like
this,
for default Ubuntu operating system for example it's www-data.

1. Repeat the createuser step of the installation instructions.

2. Give the user permission to existing tables

GRANT usage ON SCHEMA public TO "www-data";
   GRANT SELECT ON ALL TABLES IN SCHEMA public TO "www-data";

Setup fails with "DB Error: extension not found" Copy Section

Make sure you have the PostgreSQL extensions "hstore" and "postgis" installed.
See the installation instructions for a full list of required packages.

UnicodeEncodeError: 'ascii' codec can't encode character Copy Section

Make sure that the operating system's locale is UTF-8. With some prebuilt
images (e.g. LXC containers from Proxmox, see
discussion) or
images that optimize for size it might be missing.

On Ubuntu you can check the locale is installed:

grep UTF-8 /etc/default/locale

And install it using

dpkg-reconfigure locales

I forgot to delete the flatnodes file before starting an import. Copy Section

That's fine. For each import the flatnodes file get overwritten.
See https://help.openstreetmap.org/questions/52419/nominatim-flatnode-storage
for more information.

Running your own instance Copy Chapter

Can I import negative OSM ids into Nominatim? Copy Section

No, negative IDs are no longer supported by osm2pgsql. You can use
large 64-bit IDs that are guaranteed not to clash with OSM IDs. However,
you will not able to use a flatnode file with them.

Admin Import (`docs/admin/Import.md`) Copy Section

Importing the Database

The following instructions explain how to create a Nominatim database
from an OSM planet file. It is assumed that you have already successfully
installed the Nominatim software itself and the nominatim tool can be found
in your PATH. If this is not the case, return to the
installation page.

Creating the project directory Copy Chapter

Before you start the import, you should create a project directory for your
new database installation. This directory receives all data that is related
to a single Nominatim setup: configuration, extra data, etc. Create a project
directory apart from the Nominatim software and change into the directory:

mkdir ~/nominatim-project
cd ~/nominatim-project

In the following, we refer to the project directory as $PROJECT_DIR. To be
able to copy&paste instructions, you can export the appropriate variable:

export PROJECT_DIR=~/nominatim-project

The Nominatim tool assumes per default that the current working directory is
the project directory but you may explicitly state a different directory using
the --project-dir parameter. The following instructions assume that you run
all commands from the project directory.

!!! tip "Migration Tip"

Nominatim used to be run directly from the build directory until version 3.6.
Essentially, the build directory functioned as the project directory
for the database installation. This setup still works and can be useful for
development purposes. It is not recommended anymore for production setups.
Create a project directory that is separate from the Nominatim software.

Configuration setup in `.env` Copy Section

The Nominatim server can be customized via an .env configuration file in the
project directory. This is a file in dotenv
format which looks the same as variable settings in a standard shell environment.
You can also set the same configuration via environment variables. All
settings have a NOMINATIM_ prefix to avoid conflicts with other environment
variables.

There are lots of configuration settings you can tweak. A full reference
can be found in the chapter Configuration Settings.
Most should have a sensible default.

Flatnode files

If you plan to import a large dataset (e.g. Europe, North America, planet),
you should also enable flatnode storage of node locations. With this
setting enabled, node coordinates are stored in a simple file instead
of the database. This will save you import time and disk storage.
Add to your .env:

NOMINATIM_FLATNODE_FILE="/path/to/flatnode.file"

Replace the second part with a suitable path on your system and make sure
the directory exists. There should be at least 75GB of free space.

Downloading additional data Copy Chapter

Wikipedia/Wikidata rankings Copy Section

Wikipedia can be used as an optional auxiliary data source to help indicate
the importance of OSM features. Nominatim will work without this information
but it will improve the quality of the results if this is installed.
This data is available as a binary download. Put it into your project directory:

cd $PROJECT_DIR
wget https://nominatim.org/data/wikimedia-importance.csv.gz
wget -O secondary_importance.sql.gz https://nominatim.org/data/wikimedia-secondary-importance.sql.gz

The files are about 400MB and add around 4GB to the Nominatim database. For
more information about importance,
see Importance Customization.

!!! tip
If you forgot to download the wikipedia rankings, then you can
also add importances after the import. Download the SQL files, then
run nominatim refresh --wiki-data --secondary-importance --importance.
Updating importances for a planet will take a couple of hours.

External postcodes Copy Section

Nominatim can use postcodes from an external source to improve searching with
postcodes. We provide precomputed postcodes sets for the US (using TIGER data)
and the UK (using the CodePoint OpenData set.
This data can be optionally downloaded into the project directory:

cd $PROJECT_DIR
wget https://nominatim.org/data/gb_postcodes.csv.gz
wget https://nominatim.org/data/us_postcodes.csv.gz

You can also add your own custom postcode sources, see
Customization of postcodes.

Choosing the data to import Copy Chapter

In its default setup Nominatim is configured to import the full OSM data
set for the entire planet. Such a setup requires a powerful machine with
at least 64GB of RAM and around 900GB of SSD hard disks. Depending on your
use case there are various ways to reduce the amount of data imported. This
section discusses these methods. They can also be combined.

Using an extract Copy Section

If you only need geocoding for a smaller region, then precomputed OSM extracts
are a good way to reduce the database size and import time.
Geofabrik offers extracts for most countries.
They even have daily updates which can be used with the update process described
in the next section. There are also
other providers for extracts.

Please be aware that some extracts are not cut exactly along the country
boundaries. As a result some parts of the boundary may be missing which means
that Nominatim cannot compute the areas for some administrative areas.

Dropping Data Required for Dynamic Updates Copy Section

About half of the data in Nominatim's database is not really used for serving
the API. It is only there to allow the data to be updated from the latest
changes from OSM. For many uses these dynamic updates are not really required.
If you don't plan to apply updates, you can run the import with the
--no-updates parameter. This will drop the dynamic part of the database as
soon as it is not required anymore.

You can also drop the dynamic part later using the following command:

nominatim freeze

Note that you still need to provide for sufficient disk space for the initial
import. So this option is particularly interesting if you plan to transfer the
database or reuse the space later.

!!! warning
The data structure for updates are also required when adding additional data
after the import, for example TIGER housenumber data.
If you plan to use those, you must not use the --no-updates parameter.
Do a normal import, add the external data and once you are done with
everything run nominatim freeze.

Reverse-only Imports Copy Section

If you only want to use the Nominatim database for reverse lookups or
if you plan to use the installation only for exports to a
photon database, then you can set up a database
without search indexes. Add --reverse-only to your setup command above.

This saves about 5% of disk space, import time won't be significant faster.

Filtering Imported Data Copy Section

Nominatim normally sets up a full search database containing administrative
boundaries, places, streets, addresses and POI data. There are also other
import styles available which only read selected data:

• admin
  Only import administrative boundaries and places.
• street
  Like the admin style but also adds streets.
• address
  Import all data necessary to compute addresses down to house number level.
• full
  Default style that also includes points of interest.
• extratags
  Like the full style but also adds most of the OSM tags into the extratags
  column.

The style can be changed with the configuration NOMINATIM_IMPORT_STYLE.

To give you an idea of the impact of using the different styles, the table
below gives rough estimates of the final database size after import of a
2020 planet and after using the --drop option. It also shows the time
needed for the import on a machine with 64GB RAM, 4 CPUS and NVME disks.
Note that the given sizes are just an estimate meant for comparison of
style requirements. Your planet import is likely to be larger as the
OSM data grows with time.

You can also customize the styles further.
A description of the style format
can be found in the customization guide.

Initial import of the data Copy Chapter

!!! danger "Important"
First try the import with a small extract, for example from
Geofabrik.

Download the data to import. Then issue the following command
from the project directory to start the import:

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

The project directory is the one that you have set up at the beginning.
See creating the project directory.

Notes on full planet imports Copy Section

Even on a perfectly configured machine
the import of a full planet takes around 2 days. Once you see messages
with Rank .. ETA appear, the indexing process has started. This part takes
the most time. There are 30 ranks to process. Rank 26 and 30 are the most complex.
They take each about a third of the total import time. If you have not reached
rank 26 after two days of import, it is worth revisiting your system
configuration as it may not be optimal for the import.

Notes on memory usage Copy Section

In the first step of the import Nominatim uses osm2pgsql
to load the OSM data into the PostgreSQL database. This step is very demanding
in terms of RAM usage. osm2pgsql and PostgreSQL are running in parallel at
this point. PostgreSQL blocks at least the part of RAM that has been configured
with the shared_buffers parameter during
PostgreSQL tuning
and needs some memory on top of that. osm2pgsql needs at least 2GB of RAM for
its internal data structures, potentially more when it has to process very large
relations. In addition it needs to maintain a cache for node locations. The size
of this cache can be configured with the parameter --osm2pgsql-cache.

When importing with a flatnode file, it is best to disable the node cache
completely and leave the memory for the flatnode file. Nominatim will do this
by default, so you do not need to configure anything in this case.

For imports without a flatnode file, set --osm2pgsql-cache approximately to
the size of the OSM pbf file you are importing. The size needs to be given in
MB. Make sure you leave enough RAM for PostgreSQL and osm2pgsql as mentioned
above. If the system starts swapping or you are getting out-of-memory errors,
reduce the cache size or even consider using a flatnode file.

Testing the installation Copy Section

Run this script to verify that all required tables and indices got created
successfully.

nominatim admin --check-database

If you have installed the nominatim-api package, then you can try out
your installation by executing a simple query on the command line:

nominatim search --query Berlin

or, when you have a reverse-only installation:

nominatim reverse --lat 51 --lon 45

If you want to run Nominatim as a service, make sure you have installed
the right packages as per Installation.

Testing the Python frontend

To run the test server against the Python frontend, you must choose a
web framework to use, either starlette or falcon. Make sure the appropriate
packages are installed. Then run

nominatim serve

or, if you prefer to use Starlette instead of Falcon as webserver,

nominatim serve --engine starlette

Go to http://localhost:8088/status and you should see the message OK.
You can also run a search query, e.g. http://localhost:8088/search?q=Berlin
or, for reverse-only installations a reverse query,
e.g. http://localhost:8088/reverse?lat=27.1750090510034&lon=78.04209025.

Do not use this test server in production.
To run Nominatim via webservers like Apache or nginx, please continue reading
Deploy the Python frontend.

Enabling search by category phrases Copy Chapter

To be able to search for places by their type using
special phrases
you also need to import these key phrases like this:

nominatim special-phrases --import-from-wiki

Note that this command downloads the phrases from the wiki link above. You
need internet access for the step.

You can also import special phrases from a csv file, for more
information please see the Customization part.

Admin Installation (`docs/admin/Installation.md`) Copy Section

Basic Installation

This page contains generic installation instructions for Nominatim and its
prerequisites. There are also step-by-step instructions available for
the following operating systems:

• Ubuntu 24.04
• Ubuntu 22.04

These OS-specific instructions can also be found in executable form
in the vagrant/ directory.

Users have created instructions for other frameworks. We haven't tested those
and can't offer support.

• Docker
• Docker on Kubernetes
• Kubernetes with Helm
• Ansible

Prerequisites Copy Chapter

Software Copy Section

For running Nominatim:

• PostgreSQL (13+)
• PostGIS (3.0+ will work, 3.2+ strongly recommended)
• osm2pgsql (1.8+)
• Python 3 (3.9+, 3.10+ in case of Windows)

Furthermore the following Python libraries are required:

• Psycopg3
• Python Dotenv
• psutil
• Jinja2
• PyICU
• PyYaml (5.1+)
• mwparserfromhell

These will be installed automatically when using pip installation.

For running continuous updates:

• pyosmium

For running the Python frontend:

• SQLAlchemy (1.4.31+, below 2.1, with greenlet support)
• asyncpg (0.8+, only when using SQLAlchemy < 2.0)
• one of the following web frameworks:
  • falcon (3.0+)
  • starlette
• uvicorn

For dependencies for running tests and building documentation, see
the Development section.

Hardware Copy Section

A minimum of 2GB of RAM is required or installation will fail. For a full
planet import 128GB of RAM or more are strongly recommended. Do not report
out of memory problems if you have less than 64GB RAM.

For a full planet install you will need at least 1TB of hard disk space.
Take into account that the OSM database is growing fast.
Fast disks are essential. Using NVME disks is recommended.

Even on a well configured machine the import of a full planet takes
around 2.5 days. When using traditional SSDs, 4-5 days are more realistic.

Tuning the PostgreSQL database Copy Chapter

You might want to tune your PostgreSQL installation so that the later steps
make best use of your hardware. You should tune the following parameters in
your postgresql.conf file.

shared_buffers = 2GB
maintenance_work_mem = (10GB)
autovacuum_work_mem = 2GB
work_mem = (50MB)
synchronous_commit = off
max_wal_size = 1GB
checkpoint_timeout = 60min
checkpoint_completion_target = 0.9
random_page_cost = 1.0
wal_level = minimal
max_wal_senders = 0

The numbers in brackets behind some parameters seem to work fine for
128GB RAM machine. Adjust to your setup. A higher number for max_wal_size
means that PostgreSQL needs to run checkpoints less often but it does require
the additional space on your disk.

Autovacuum must not be switched off because it ensures that the
tables are frequently analysed. If your machine has very little memory,
you might consider setting:

autovacuum_max_workers = 1

and even reduce autovacuum_work_mem further. This will reduce the amount
of memory that autovacuum takes away from the import process.

Installing the latest release Copy Chapter

Nominatim is easiest installed directly from Pypi. Make sure you have installed
osm2pgsql, PostgreSQL/PostGIS and libICU together with its header files.

Then you can install Nominatim with:

pip install nominatim-db nominatim-api

Downloading and building Nominatim Copy Chapter

Downloading the latest release Copy Section

You can download the latest release from nominatim.org.
The release contains all necessary files. Just unpack it.

Downloading the latest development version Copy Section

If you want to install latest development version from github:

git clone https://github.com/osm-search/Nominatim.git

The development version does not include the country grid. Download it separately:

wget -O Nominatim/data/country_osm_grid.sql.gz https://nominatim.org/data/country_grid.sql.gz

Building Nominatim Copy Section

Nominatim is easiest to run from its own virtual environment. To create one, run:

sudo apt-get install virtualenv
virtualenv /srv/nominatim-venv

To install Nominatim directly from the source tree into the virtual environment, run:

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

Now continue with importing the database.

Admin Maintenance (`docs/admin/Maintenance.md`) Copy Section

This chapter describes the various operations the Nominatim database administrator
may use to clean and maintain the database. None of these operations is mandatory
but they may help improve the performance and accuracy of results.

Updating postcodes Copy Chapter

Command: nominatim refresh --postcodes

Postcode centroids (aka 'calculated postcodes') are generated by looking at all
postcodes of a country, grouping them and calculating the geometric centroid.
There is currently no logic to deal with extreme outliers (typos or other
mistakes in OSM data). There is also no check if a postcodes adheres to a
country's format, e.g. if Swiss postcodes are 4 digits.

When running regular updates, postcodes results can be improved by running
this command on a regular basis. Note that only the postcode table and the
postcode search terms are updated. The postcode that is assigned to each place
is only updated when the place is updated.

The command takes around 70min to run on the planet and needs ca. 40GB of
temporary disk space.

Updating word counts Copy Chapter

Command: nominatim refresh --word-counts

Nominatim keeps frequency statistics about all search terms it indexes. These
statistics are currently used to optimise queries to the database. Thus better
statistics mean better performance. Word counts are created once after import
and are usually sufficient even when running regular updates. You might want
to rerun the statistics computation when adding larger amounts of new data,
for example, when adding an additional country via nominatim add-data.

Forcing recomputation of places and areas Copy Chapter

Command: nominatim refresh --data-object [NWR] --data-area [NWR]

When running replication updates, Nominatim tries to recompute the search
and address information for all places that are affected by a change. But it
needs to restrict the total number of changes to make sure it can keep up
with the minutely updates. Therefore it will refrain from propagating changes
that affect a lot of objects.

The administrator may force an update of places in the database.
nominatim refresh --data-object invalidates a single OSM object.
nominatim refresh --data-area invalidates an OSM object and all dependent
objects. That are usually the places that inside its area or around the
center of the object. Both commands expect the OSM object as an argument
of the form OSM type + OSM id. The type must be N (node), W (way) or
R (relation).

After invalidating the object, indexing must be run again. If continuous
update are running in the background, the objects will be recomputed together
with the next round of updates. Otherwise you need to run nominatim index
to finish the recomputation.

Removing large deleted objects Copy Chapter

Command: nominatim admin --clean-deleted

Nominatim refuses to delete very large areas because often these deletions are
accidental and are reverted within hours. Instead the deletions are logged in
the import_polygon_delete table and left to the administrator to clean up.

To run this command you will need to pass a PostgreSQL time interval. For example to
delete any objects that have been deleted more than a month ago you would run:
nominatim admin --clean-deleted '1 month'

Admin Migration (`docs/admin/Migration.md`) Copy Section

Database Migrations

Nominatim offers automatic migrations for versions 4.3+. Please follow
the following steps:

• Stop any updates that are potentially running
• Update the backend: pip install -U nominatim-db
• Go to your project directory and run nominatim admin --migrate
• Update the frontend: pip install -U nominatim-api
• (optionally) Restart updates

Below you find additional migrations and hints about other structural and
breaking changes. Please read them before running the migration.

!!! note
If you are migrating from a version <4.3, you need to install 4.3
and migrate to 4.3 first. Then you can migrate to the current
version. It is strongly recommended to do a reimport instead.

5.3.0 -> 5.4.0 Copy Chapter

Places are classified by categories now Copy Section

Places have a new categories column on the place and placex tables. It
holds the main tags of a place as hierarchical labels of the form
osm.<class>.<type>, see
Database layout. The migration
adds the column and fills it in placex from the class and type of the
existing rows.

The backfill only covers what the category search needs: the places that make
up an address above street level and the POI categories that have a special
phrase. A migrated database also keeps its old layout of one row per main tag.
Reimport if you want the new include and exclude filters of the
search API to find a place under all of
its main tags.

The place_classtype tables are not used anymore Copy Section

Category search now runs against the categories column of placex, so the
per-category place_classtype_* tables are not created or updated anymore.
The migration leaves the existing tables in place because the old frontend
code still queries them until you have restarted it with the new version.

Once all your frontends run the new version, you can drop the tables to free
the disk space. On a planet database that is a couple of hundred tables and
several GB. To generate the necessary SQL, run:

SELECT format('DROP TABLE IF EXISTS %I;', tablename)
  FROM pg_tables
  WHERE schemaname = 'public' AND tablename LIKE 'place\_classtype\_%';

The --min option of nominatim special-phrases only restricted which of
those tables were created. It has no effect anymore and is deprecated. It
will be removed in a future version.

5.2.0 -> 5.3.0 Copy Chapter

Expensive table migrations

This version introduces new tables for postcodes, interpolations and
associatedStreet relations. Migration is possible but will take a bit
longer. It is recommended to take Nominatim offline while migrating to 5.3.

5.1.0 -> 5.2.0 Copy Chapter

Lua import style: required extratags removed Copy Section

Tags that are required by Nominatim as extratags are now always included
independent of what is defined in the style. The line

flex.add_for_extratags('required')

is no longer required in custom styles and will throw an error. Simply
remove the line from your style.

4.5.0 -> 5.0.0 Copy Chapter

PHP frontend removed Copy Section

The PHP frontend has been completely removed. Please switch to the Python
frontend.

Without the PHP code, the nominatim refresh --website command is no longer
needed. It currently omits a warning and does otherwise nothing. It will be
removed in later versions of Nominatim. So make sure you remove it from your
scripts.

CMake building removed Copy Section

Nominatim can now only be installed via pip. Please follow the installation
instructions for the current version to change to pip.

osm2pgsql no longer vendored in Copy Section

Nominatim no longer ships its own version of osm2pgsql. Please install a
stock version of osm2pgsql from your distribution. See the
installation instruction for osm2pgsql
for details. A minimum version of 1.8 is required. The current stable versions
of Ubuntu and Debian already ship with an appropriate versions. For older
installations, you may have to compile a newer osm2pgsql yourself.

Legacy tokenizer removed Copy Section

The legacy tokenizer is no longer enabled. This tokenizer has been superseded
by the ICU tokenizer a long time ago. In the unlikely case that your database
still uses the legacy tokenizer, you must reimport your database.

osm2pgsql style overhauled Copy Section

There are some fundamental changes to how customized osm2pgsql styles should
be written. The changes are mostly backwards compatible, i.e. custom styles
should still work with the new implementation. The only exception is a
customization of the process_tags() function. This function is no longer
considered public and neither are the helper functions used in it.
They currently still work but will be removed at some point. If you have
been making changes to process_tags, please review your style and try
to switch to the new convenience functions.

For more information on the changes, see the
pull request
and read the new
customization documentation.

4.4.0 -> 4.5.0 Copy Chapter

New structure for Python packages Copy Section

The nominatim Python package has been split into nominatim-db and nominatim-api.
Any imports need to be adapted accordingly.

If you are running the Python frontend, change the server module from
nominatim.server.falcon.server to nominatim_api.server.falcon.server.

If you are using the Nominatim library, all imports need to be changed
from nominatim.api.<module> to nominatim_api.<module>.

If you have written custom tokenizers or sanitizers, the appropriate modules
are now found in nominatim_db.

4.2.0 -> 4.3.0 Copy Chapter

New indexes for reverse lookup Copy Section

The reverse lookup algorithm has changed slightly to improve performance.
This change needs a different index in the database. The required index
will be automatically build during migration. Until the new index is available
performance of the /reverse endpoint is significantly reduced. You should
therefore either remove traffic from the machine before attempting a
version update or create the index manually before starting the update
using the following SQL:

CREATE INDEX IF NOT EXISTS idx_placex_geometry_reverse_lookupPlaceNode
  ON placex USING gist (ST_Buffer(geometry, reverse_place_diameter(rank_search)))
  WHERE rank_address between 4 and 25 AND type != 'postcode'
    AND name is not null AND linked_place_id is null AND osm_type = 'N';

4.0.0 -> 4.1.0 Copy Chapter

ICU tokenizer is the new default Copy Section

Nominatim now installs the ICU tokenizer
by default. This only has an effect on newly installed databases. When
updating older databases, it keeps its installed tokenizer. If you still
run with the legacy tokenizer, make sure to compile Nominatim with the
PostgreSQL module, see Installation.

geocodejson output changed Copy Section

The type field of the geocodejson output has changed. It now contains
the address class of the object instead of the value of the OSM tag. If
your client has used the type field, switch them to read osm_value
instead.

3.7.0 -> 4.0.0 Copy Chapter

NOMINATIM_PHRASE_CONFIG removed Copy Section

Custom blacklist configurations for special phrases now need to be handed
with the --config parameter to nominatim special-phrases. Alternatively
you can put your custom configuration in the project directory in a file
named phrase-settings.json.

Version 3.8 also removes the automatic converter for the php format of
the configuration in older versions. If you are updating from Nominatim < 3.7
and still work with a custom phrase-settings.php, you need to manually
convert it into a json format.

PHP utils removed Copy Section

The old PHP utils have now been removed completely. You need to switch to
the appropriate functions of the nominatim command line tool. See
Introducing nominatim command line tool
below.

3.6.0 -> 3.7.0 Copy Chapter

New format and name of configuration file Copy Section

The configuration for an import is now saved in a .env file in the project
directory. This file follows the dotenv format. For more information, see
the installation chapter.

To migrate to the new system, create a new project directory, add the .env
file and port your custom configuration from settings/local.php. Most
settings are named similar and only have received a NOMINATIM_ prefix.
Use the default settings in settings/env.defaults as a reference.

New location for data files Copy Section

External data files for Wikipedia importance, postcodes etc. are no longer
expected to reside in the source tree by default. Instead they will be searched
in the project directory. If you have an automated setup script you must
either adapt the download location or explicitly set the location of the
files to the old place in your .env.

Introducing `nominatim` command line tool Copy Section

The various php utilities have been replaced with a single nominatim
command line tool. Make sure to adapt any scripts. There is no direct 1:1
matching between the old utilities and the commands of nominatim CLI. The
following list gives you a list of nominatim sub-commands that contain
functionality of each script:

• ./utils/setup.php: import, freeze, refresh
• ./utils/update.php: replication, add-data, index, refresh
• ./utils/specialphrases.php: special-phrases
• ./utils/check_import_finished.php: admin
• ./utils/warm.php: admin
• ./utils/export.php: export

Try nominatim <command> --help for more information about each subcommand.

./utils/query.php no longer exists in its old form. nominatim search
provides a replacement but returns different output.

Switch to normalized house numbers Copy Section

The housenumber column in the placex table uses now normalized version.
The automatic migration step will convert the column but this may take a
very long time. It is advisable to take the machine offline while doing that.

3.5.0 -> 3.6.0 Copy Chapter

Change of layout of search_name_* tables Copy Section

The table need a different index for nearest place lookup. Recreate the
indexes using the following shell script:

for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`;
do
    psql -d nominatim -c "DROP INDEX idx_${table}_centroid_place; CREATE INDEX idx_${table}_centroid_place ON ${table} USING gist (centroid) WHERE ((address_rank >= 2) AND (address_rank <= 25)); DROP INDEX idx_${table}_centroid_street; CREATE INDEX idx_${table}_centroid_street ON ${table} USING gist (centroid) WHERE ((address_rank >= 26) AND (address_rank <= 27))";
done

Removal of html output Copy Section

The debugging UI is no longer directly provided with Nominatim. Instead we
now provide a simple Javascript application. Please refer to
Setting up the Nominatim UI for details on how to
set up the UI.

The icons served together with the API responses have been moved to the
nominatim-ui project as well. If you want to keep the icon field in the
response, you need to set CONST_MapIcon_URL to the URL of the /mapicon
directory of nominatim-ui.

Change order during indexing Copy Section

When reindexing places during updates, there is now a different order used
which needs a different database index. Create it with the following SQL command:

CREATE INDEX idx_placex_pendingsector_rank_address
  ON placex
  USING BTREE (rank_address, geometry_sector)
  WHERE indexed_status > 0;

You can then drop the old index with:

DROP INDEX idx_placex_pendingsector;

Unused index Copy Section

This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.

DROP INDEX idx_placex_geometry_reverse_lookupPoint;

Switching to dotenv Copy Section

As part of the work changing the configuration format, the configuration for
the website is now using a separate configuration file. To create the
configuration file, run the following command after updating:

./utils/setup.php --setup-website

Update SQL code Copy Section

To update the SQL code to the leatest version run:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

3.4.0 -> 3.5.0 Copy Chapter

New Wikipedia/Wikidata importance tables Copy Section

The wikipedia_* tables have a new format that also includes references to
Wikidata. You need to update the computation functions and the tables as
follows:

• download the new Wikipedia tables as described in the import section
• reimport the tables: ./utils/setup.php --import-wikipedia-articles
• update the functions: ./utils/setup.php --create-functions --enable-diff-updates
• create a new lookup index:

CREATE INDEX idx_placex_wikidata
  ON placex
  USING BTREE ((extratags -> 'wikidata'))
  WHERE extratags ? 'wikidata'
    AND class = 'place'
    AND osm_type = 'N'
    AND rank_search < 26;

• compute importance: ./utils/update.php --recompute-importance

The last step takes about 10 hours on the full planet.

Remove one function (it will be recreated in the next step):

DROP FUNCTION create_country(hstore,character varying);

Finally, update all SQL functions:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

3.3.0 -> 3.4.0 Copy Chapter

Reorganisation of location_area_country table Copy Section

The table location_area_country has been optimized. You need to switch to the
new format when you run updates. While updates are disabled, run the following
SQL commands:

CREATE TABLE location_area_country_new AS
  SELECT place_id, country_code, geometry FROM location_area_country;
DROP TABLE location_area_country;
ALTER TABLE location_area_country_new RENAME TO location_area_country;
CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);

Finally, update all SQL functions:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

3.2.0 -> 3.3.0 Copy Chapter

New database connection string (DSN) format Copy Section

Previously database connection setting (CONST_Database_DSN in settings/*.php) had the format

• (simple) pgsql://@/nominatim
• (complex) pgsql://johndoe:[email protected]:1234/db1

The new format is

• (simple) pgsql:dbname=nominatim
• (complex) pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret

Natural Earth country boundaries no longer needed as fallback Copy Section

DROP TABLE country_naturalearthdata;

Finally, update all SQL functions:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

Configurable Address Levels Copy Section

The new configurable address levels require a new table. Create it with the
following command:

./utils/update.php --update-address-levels

3.1.0 -> 3.2.0 Copy Chapter

New reverse algorithm Copy Section

The reverse algorithm has changed and requires new indexes. Run the following
SQL statements to create the indexes:

CREATE INDEX idx_placex_geometry_reverse_lookupPoint
  ON placex
  USING gist (geometry)
  WHERE (name IS NOT null or housenumber IS NOT null or rank_address BETWEEN 26 AND 27)
    AND class NOT IN ('railway','tunnel','bridge','man_made')
    AND rank_address >= 26
    AND indexed_status = 0
    AND linked_place_id IS null;
CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
  ON placex USING gist (geometry)
  WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
    AND rank_address between 4 and 25
    AND type != 'postcode'
    AND name is not null
    AND indexed_status = 0
    AND linked_place_id is null;
CREATE INDEX idx_placex_geometry_reverse_placeNode
  ON placex USING gist (geometry)
  WHERE osm_type = 'N'
    AND rank_search between 5 and 25
    AND class = 'place'
    AND type != 'postcode'
    AND name is not null
    AND indexed_status = 0
    AND linked_place_id is null;

You also need to grant the website user access to the country_osm_grid table:

GRANT SELECT ON table country_osm_grid to "www-user";

Replace the www-user with the user name of your website server if necessary.

You can now drop the unused indexes:

DROP INDEX idx_placex_reverse_geometry;

Finally, update all SQL functions:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

3.0.0 -> 3.1.0 Copy Chapter

Postcode Table Copy Section

A new separate table for artificially computed postcode centroids was introduced.
Migration to the new format is possible but not recommended.

Create postcode table and indexes, running the following SQL statements:

CREATE TABLE location_postcode
  (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
   rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
   country_code varchar(2), postcode TEXT,
   geometry GEOMETRY(Geometry, 4326));
CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
GRANT SELECT ON location_postcode TO "www-data";
DROP TYPE IF EXISTS nearfeaturecentr CASCADE;
CREATE TYPE nearfeaturecentr AS (
  place_id BIGINT,
  keywords int[],
  rank_address smallint,
  rank_search smallint,
  distance float,
  isguess boolean,
  postcode TEXT,
  centroid GEOMETRY
);

Add postcode column to location_area tables with SQL statement:

ALTER TABLE location_area ADD COLUMN postcode TEXT;

Then reimport the functions:

./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions

Create appropriate triggers with SQL:

CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
    FOR EACH ROW EXECUTE PROCEDURE postcode_update();

Finally populate the postcode table (will take a while):

./utils/setup.php --calculate-postcodes --index --index-noanalyse

This will create a working database. You may also delete the old artificial
postcodes now. Note that this may be expensive and is not absolutely necessary.
The following SQL statement will remove them:

DELETE FROM place_addressline a USING placex p
 WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
ALTER TABLE placex DISABLE TRIGGER USER;
DELETE FROM placex WHERE osm_type = 'P';
ALTER TABLE placex ENABLE TRIGGER USER;

Admin Setup Nominatim UI (`docs/admin/Setup-Nominatim-UI.md`) Copy Section

Setting up the Nominatim UI

Nominatim is a search API, it does not provide a website interface on its
own. nominatim-ui offers a
small website for testing your setup and inspecting the database content.

This section provides a quick start how to use nominatim-ui with your
installation. For more details, please also have a look at the
README of nominatim-ui.

Installing nominatim-ui Copy Chapter

We provide regular releases of nominatim-ui that contain the packaged website.
They do not need any special installation. Just download, configure
and run it. Grab the latest release from
nominatim-ui's Github release page
and unpack it. You can use nominatim-ui-x.x.x.tar.gz or nominatim-ui-x.x.x.zip.

Next you need to adapt the UI to your installation. Custom settings need to be
put into dist/theme/config.theme.js. At a minimum you need to
set Nominatim_API_Endpoint to point to your Nominatim installation:

cd nominatim-ui
echo "Nominatim_Config.Nominatim_API_Endpoint='https://myserver.org/nominatim/';" > dist/theme/config.theme.js

For the full set of available settings, have a look at dist/config.defaults.js.

Then you can just test it locally by spinning up a webserver in the dist
directory. For example, with Python:

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

The website is now available at http://localhost:8765.

Forwarding searches to nominatim-ui Copy Chapter

Nominatim used to provide the search interface directly by itself when
format=html was requested. For the /search endpoint this even used
to be the default.

The following section describes how to set up Apache or nginx, so that your
users are forwarded to nominatim-ui when they go to a URL that formerly presented
the UI.

Setting up forwarding in Nginx Copy Section

First of all make nominatim-ui available under /ui on your webserver:

server {

    # Here is the Nominatim setup as described in the Installation section

    location /ui/ {
        alias <full path to the nominatim-ui directory>/dist/;
        index index.html;
    }
}

Now we need to find out if a URL should be forwarded to the UI. Add the
following map commands outside the server section:

# Inspect the format parameter in the query arguments. We are interested
# if it is set to html or something else or if it is missing completely.
map $args $format {
    default                  default;
    ~(^|&)format=html(&|$)   html;
    ~(^|&)format=            other;
}

# Determine from the URI and the format parameter above if forwarding is needed.
map $uri/$format $forward_to_ui {
    default               0;  # no forwarding by default
    ~/search.*/default    1;  # Use this line only, if search should go to UI by default.
    ~/reverse.*/html      1;  # Forward API calls that UI supports, when
    ~/status.*/html       1;  #   format=html is explicitly requested.
    ~/search.*/html       1;
    ~/details.*/html      1;
}

The $forward_to_ui parameter can now be used to conditionally forward the
calls:

location / {
    if ($forward_to_ui) {
        rewrite ^(/[^/.]*) https://$http_host/ui$1.html redirect;
    }

    # proxy_pass commands
}

Reload nginx and the UI should be available.

Setting up forwarding in Apache Copy Section

First of all make nominatim-ui available in the ui/ subdirectory where
Nominatim is installed. For example, given you have set up an alias under
nominatim like this:

Alias /nominatim /home/vagrant/build/website

you need to insert the following rules for nominatim-ui before that alias:

<Directory "/home/vagrant/nominatim-ui/dist">
  DirectoryIndex search.html
  Require all granted
</Directory>

Alias /nominatim/ui /home/vagrant/nominatim-ui/dist

Replace /home/vagrant/nominatim-ui with the directory where you have cloned
nominatim-ui.

!!! important
The alias for nominatim-ui must come before the alias for the Nominatim
website directory.

To set up forwarding, the Apache rewrite module is needed. Enable it with:

sudo a2enmod rewrite

Then add rewrite rules to the Directory directive of the Nominatim website
directory like this:

<Directory "/home/vagrant/build/website">
  Options FollowSymLinks MultiViews
  AddType text/html   .php
  Require all granted

  RewriteEngine On

  # This must correspond to the URL where nominatim can be found.
  RewriteBase "/nominatim/"

  # If no endpoint is given, then use search.
  RewriteRule ^(/|$)   "search"

  # If format-html is explicitly requested, forward to the UI.
  RewriteCond %{QUERY_STRING} "format=html"
  RewriteRule ^([^/.]+) ui/$1.html [R,END]

  # Optionally: if no format parameter is there then forward /search.
  RewriteCond %{QUERY_STRING} "!format="
  RewriteCond %{REQUEST_URI}  "/search"
  RewriteRule ^([^/.]+) ui/$1.html [R,END]
</Directory>

Restart Apache and the UI should be available.

Admin Update (`docs/admin/Update.md`) Copy Section

Updating the Database

There are many different ways to update your Nominatim database.
The following section describes how to keep it up-to-date using
an online replication service for OpenStreetMap data
For a list of other methods to add or update data see the output of
nominatim add-data --help.

!!! important
If you have configured a flatnode file for the import, then you
need to keep this flatnode file around for updates.

Installing the newest version of Pyosmium Copy Section

The replication process uses
Pyosmium
to download update data from the server.
It is recommended to install Pyosmium via pip.
Run (as the same user who will later run the updates):

pip3 install --user osmium

Setting up the update process Copy Section

Next the update process needs to be initialised. By default Nominatim is configured
to update using the global minutely diffs.

If you want a different update source you will need to add some settings
to .env. For example, to use the daily country extracts
diffs for Ireland from Geofabrik add the following:

# 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

To set up the update process now run the following command:

nominatim replication --init

It outputs the date where updates will start. Recheck that this date is
what you expect.

The replication --init command needs to be rerun whenever the replication
service is changed.

Updating Nominatim Copy Section

Nominatim supports different modes how to retrieve the update data from the
server. Which one you want to use depends on your exact setup and how often you
want to retrieve updates.

These instructions are for using a single source of updates. If you have
imported multiple country extracts and want to keep them
up-to-date, Advanced installations section
contains instructions to set up and update multiple country extracts.

One-time mode

When the --once parameter is given, then Nominatim will download exactly one
batch of updates and then exit. This one-time mode still respects the
NOMINATIM_REPLICATION_UPDATE_INTERVAL that you have set. If according to
the update interval no new data has been published yet, it will go to sleep
until the next expected update and only then attempt to download the next batch.

The one-time mode is particularly useful if you want to run updates continuously
but need to schedule other work in between updates. For example, you might
want to regularly recompute postcodes -- a process that
must not be run while updates are in progress. An update script refreshing
postcodes regularly might look like this:

#!/bin/bash

# Switch to your project directory.
cd /srv/nominatim

while true; do
  nominatim replication --once
  if [ -f "/srv/nominatim/schedule-maintenance" ]; then
    rm /srv/nominatim/schedule-maintenance
    nominatim refresh --postcodes
  fi
done

A cron job then creates the file /srv/nominatim/schedule-maintenance once per night.

One-time mode with systemd

You can run the one-time mode with a systemd timer & service.

Create a timer description like /etc/systemd/system/nominatim-updates.timer:

[Unit]
Description=Timer to start updates of Nominatim

[Timer]
OnActiveSec=2
OnUnitActiveSec=1min
Unit=nominatim-updates.service

[Install]
WantedBy=multi-user.target

OnUnitActiveSec defines how often the individual update command is run.

Then add a service definition for the timer in /etc/systemd/system/nominatim-updates.service:

[Unit]
Description=Single updates of Nominatim

[Service]
WorkingDirectory=/srv/nominatim-project
ExecStart=/srv/nominatim-venv/bin/nominatim replication --once
StandardOutput=journal
StandardError=inherit
User=nominatim
Group=nominatim
Type=simple

[Install]
WantedBy=multi-user.target

Replace the WorkingDirectory with your project directory. ExecStart points
to the nominatim binary that was installed in your virtualenv earlier.
Finally, you might need to adapt user and group names as required.

Now activate the service and start the updates:

sudo systemctl daemon-reload
sudo systemctl enable nominatim-updates.timer
sudo systemctl start nominatim-updates.timer

You can stop future data updates while allowing any current, in-progress
update steps to finish, by running sudo systemctl stop nominatim-updates.timer and waiting until nominatim-updates.service isn't
running (sudo systemctl is-active nominatim-updates.service).

To check the output from the update process, use journalctl: journalctl -u nominatim-updates.service

Catch-up mode

With the --catch-up parameter, Nominatim will immediately try to download
all changes from the server until the database is up-to-date. The catch-up mode
still respects the parameter NOMINATIM_REPLICATION_MAX_DIFF. It downloads and
applies the changes in appropriate batches until all is done.

The catch-up mode is foremost useful to bring the database up to date after the
initial import. Give that the service usually is not in production at this
point, you can temporarily be a bit more generous with the batch size and
number of threads you use for the updates by running catch-up like this:

cd /srv/nominatim-project
NOMINATIM_REPLICATION_MAX_DIFF=5000 nominatim replication --catch-up --threads 15

The catch-up mode is also useful when you want to apply updates at a lower
frequency than what the source publishes. You can set up a cron job to run
replication catch-up at whatever interval you desire.

!!! hint
When running scheduled updates with catch-up, it is a good idea to choose
a replication source with an update frequency that is an order of magnitude
lower. For example, if you want to update once a day, use an hourly updated
source. This ensures that you don't miss an entire day of updates when
the source is unexpectedly late to publish its update.

If you want to use the source with the same update frequency (e.g. a daily
updated source with daily updates), use the
once mode together with a frequently run systemd script as described above.
It ensures to re-request the newest update until they have been published.

Continuous updates

!!! danger
This mode is no longer recommended to use and will removed in future
releases. systemd is much better
suited for running regular updates. Please refer to the setup
instructions for running one-time mode with systemd above.

This is the easiest mode. Simply run the replication command without any
parameters:

nominatim replication

The update application keeps running forever and retrieves and applies
new updates from the server as they are published.

Api Details (`docs/api/Details.md`) Copy Section

Place details

Show all details about a single place saved in the database.

This API endpoint is meant for visual inspection of the data in the database,
mainly together with Nominatim-UI.
The parameters of the endpoint and the output may change occasionally between
versions of Nominatim. Do not rely on the output in scripts or applications.

!!! warning
The details endpoint at https://nominatim.openstreetmap.org
may not used in scripts or bots at all.
See Nominatim Usage Policy.

The details API supports the following three request formats:

https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>

osmtype and osmid are required parameters. The type is one of node (N), way (W)
or relation (R). The id must be a number. The class parameter is optional and
only kept for backwards compatibility. An OSM object has a single entry in
Nominatim, even when it is tagged with more than one main tag. A place tagged
with tourism=hotel and amenity=restaurant is therefore returned as one
result, classified as a restaurant. When class is given, then it must be
equal to the class of that entry or the lookup returns no result.

Databases that were migrated from a version before 5.4 may still hold one entry
per main tag. There the class parameter selects between them and, when it is
left out, one of the entries is chosen at random and displayed.

https://nominatim.openstreetmap.org/details?place_id=<value>

Place IDs are assigned sequentially during Nominatim data import. The ID
for a place is different between Nominatim installation (servers) and
changes when data gets reimported. Therefore it cannot be used as
a permanent id and shouldn't be used in bug reports.

https://nominatim.openstreetmap.org/details?postcode=<country_code>:<postcode_id>

Artificial postcodes do not always have an OSM object reference. For these,
Nominatim provides a stable postcode reference that combines the country code
and postcode. Spaces in the postcode id are replaced with underscores. For
example, us:94110 refers to postcode 94110 in the United States and
gb:EH4_7EA refers to postcode EH4 7EA in Great Britain.

!!! danger "Deprecation warning"
The API can also be used with the URL
https://nominatim.openstreetmap.org/details.php. This is now deprecated
and will be removed in future versions.

Parameters Copy Chapter

This section lists additional optional parameters.

Output format Copy Section

When set, then JSON output will be wrapped in a callback function with
the given name. See JSONP for more
information.

Output details Copy Section

When set to 1, include a breakdown of the address into elements.

When set to 1, include a list of name keywords and address keywords
in the result.

Include details of places that are linked with this one. Places get linked
together when they are different forms of the same physical object. Nominatim
links two kinds of objects together: place nodes get linked with the
corresponding administrative boundaries. Waterway relations get linked together with their
members.

Include details of POIs and address that depend on the place. Only POIs
that use this place to determine their address will be returned.

When set to 1, the output of the address hierarchy will be
grouped by type.

Include geometry of result.

When set to 1, include the tagged entrances in the result.

Language of results Copy Section

Preferred language order for showing search results. This may either be
a simple comma-separated list of language codes or have the same format
as the "Accept-Language" HTTP header.

Other Copy Section

Output special developer debug information instead of the normal result.
See Debug output for details.

Examples Copy Chapter

JSON

https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json

{
  "place_id": 85993608,
  "parent_place_id": 72765313,
  "osm_type": "W",
  "osm_id": 38210407,
  "category": "place",
  "type": "square",
  "admin_level": "15",
  "localname": "Pariser Platz",
  "names": {
    "name": "Pariser Platz",
    "name:be": "Парыжская плошча",
    "name:de": "Pariser Platz",
    "name:es": "Plaza de París",
    "name:he": "פאריזר פלאץ",
    "name:ko": "파리저 광장",
    "name:la": "Forum Parisinum",
    "name:ru": "Парижская площадь",
    "name:uk": "Паризька площа",
    "name:zh": "巴黎廣場"
  },
  "addresstags": {
    "postcode": "10117"
  },
  "housenumber": null,
  "calculated_postcode": "10117",
  "country_code": "de",
  "indexed_date": "2018-08-18T17:02:45+00:00",
  "importance": 0.339401620591472,
  "calculated_importance": 0.339401620591472,
  "extratags": {
    "wikidata": "Q156716",
    "wikipedia": "de:Pariser Platz"
  },
  "calculated_wikipedia": "de:Pariser_Platz",
  "rank_address": 30,
  "rank_search": 30,
  "isarea": true,
  "centroid": {
    "type": "Point",
    "coordinates": [
      13.3786822618517,
      52.5163654
    ]
  },
  "geometry": {
    "type": "Point",
    "coordinates": [
      13.3786822618517,
      52.5163654
    ]
  }
}

Api Faq (`docs/api/Faq.md`) Copy Section

Frequently Asked Questions

API Results Copy Chapter

1. The address of my search results contains far-away places that don't belong there.

Nominatim computes the address from two sources in the OpenStreetMap data:
from administrative boundaries and from place nodes. Boundaries are the more
useful source. They precisely describe an area. So it is very clear for
Nominatim if a point belongs to an area or not. Place nodes are more complicated.
These are only points without any precise extent. So Nominatim has to take a
guess and assume that an address belongs to the closest place node it can find.
In an ideal world, Nominatim would not need the place nodes but there are
many places on earth where there are no precise boundaries available for
all parts that make up an address. This is in particular true for the more
local address parts, like villages and suburbs. Therefore it is not possible
to completely dismiss place nodes. And sometimes they sneak in where they
don't belong.

As a OpenStreetMap mapper, you can improve the situation in two ways: if you
see a place node for which already an administrative area exists, then you
should link the two by adding the node with a 'label' role to the boundary
relation. If there is no administrative area, you can add the approximate
extent of the place and tag it place= as well.

2. When doing reverse search, the address details have parts that don't contain the point I was looking up.

There is a common misconception how the reverse API call works in Nominatim.
Reverse does not give you the address of the point you asked for. Reverse
returns the closest object to the point you asked for and then returns the
address of that object. Now, if you are close to a border, then the closest
object may be across that border. When Nominatim then returns the address,
it contains the county/state/country across the border.

3. I get different counties/states/countries when I change the zoom parameter in the reverse query. How is that possible?

This is basically the same problem as in the previous answer.
The zoom level influences at which search rank Nominatim starts looking
for the closest object. So the closest house number maybe on one side of the
border while the closest street is on the other. As the address details contain
the address of the closest object found, you might sometimes get one result,
sometimes the other for the closest point.

4. Can you return the continent?

Nominatim assigns each map feature one country. Those outside any administrative
boundaries are assigned a special no-country. Continents or other super-national
administrations (e.g. European Union, NATO, Custom unions) are not supported,
see also Administrative Boundary.

5. Can you return the timezone?

See this separate OpenStreetMap-based project Timezone Boundary Builder.

6. I want to download a list of streets/restaurants of a city/region

The Overpass API is more
suited for these kinds of queries.

That said if you installed your own Nominatim instance you can use the
nominatim export PHP script as basis to return such lists.

7. My result has a wrong postcode. Where does it come from?

Most places in OSM don't have a postcode, so Nominatim tries to interpolate
one. It first look at all the places that make up the address of the place.
If one of them has a postcode defined, this is the one to be used. When
none of the address parts has a postcode either, Nominatim interpolates one
from the surrounding objects. If the postcode is for your result is one, then
most of the time there is an OSM object with the wrong postcode nearby.

To find the bad postcode, go to
https://nominatim.openstreetmap.org
and search for your place. When you have found it, click on the 'details' link
under the result to go to the details page. There is a field 'Computed Postcode'
which should display the bad postcode. Click on the 'how?' link. A small
explanation text appears. It contains a link to a query for Overpass Turbo.
Click on that and you get a map with all places in the area that have the bad
postcode. If none is displayed, zoom the map out a bit and then click on 'Run'.

Now go to OpenStreetMap and fix the error you
have just found. It will take at least a day for Nominatim to catch up with
your data fix. Sometimes longer, depending on how much editing activity is in
the area.

Api Lookup (`docs/api/Lookup.md`) Copy Section

Address lookup

The lookup API allows to query the address and other details of one or
multiple OSM objects like node, way or relation.

Endpoint Copy Chapter

The lookup API has the following format:

https://nominatim.openstreetmap.org/lookup?osm_ids=[N|W|R]<value>,…,…,&<params>

osm_ids is mandatory and must contain a comma-separated list of OSM ids each
prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids
can be queried at the same time.

!!! danger "Deprecation warning"
The API can also be used with the URL
https://nominatim.openstreetmap.org/lookup.php. This is now deprecated
and will be removed in future versions.

Parameters Copy Chapter

This section lists additional optional parameters.

Output format Copy Section

See Place Output Formats for details on each format.

When given, then JSON output will be wrapped in a callback function with
the given name. See JSONP for more
information.

Only has an effect for JSON output formats.

Output details Copy Section

When set to 1, include a breakdown of the address into elements.
The exact content of the address breakdown depends on the output format.

!!! tip
If you are interested in a stable classification of address categories
(suburb, city, state, etc), have a look at the geocodejson format.
All other formats return classifications according to OSM tagging.
There is a much larger set of categories and they are not always consistent,
which makes them very hard to work with.

When set to 1, the response include any additional information in the result
that is available in the database, e.g. wikipedia link, opening hours.

When set to 1, include a full list of names for the result. These may include
language variants, older names, references and brand.

When set to 1, include the tagged entrances in the result.

Language of results Copy Section

Preferred language order for showing search results. This may either be
a simple comma-separated list of language codes or have the same format
as the "Accept-Language" HTTP header.

!!! tip
First-time users of Nominatim tend to be confused that they get different
results when using Nominatim in the browser versus in a command-line tool
like wget or curl. The command-line tools
usually don't send any Accept-Language header, prompting Nominatim
to show results in the local language. Browsers on the contrary always
send the currently chosen browser language.

Polygon output Copy Section

Add the full geometry of the place to the result output. Output formats
in GeoJSON, KML, SVG or WKT are supported. Only one of these
options can be used at a time.

When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry.

Other Copy Section

If you are making large numbers of request please include an appropriate email
address to identify your requests. See Nominatim's
Usage Policy for more details.

Output special developer debug information instead of the normal result.
See Debug output for details.

Examples Copy Chapter

XML

https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189

/* Detailed source-code truncated for AI context efficiency. */

JSON with extratags

https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json&extratags=1

/* Detailed source-code truncated for AI context efficiency. */

Api Output (`docs/api/Output.md`) Copy Section

Place Output

The /reverse, /search and /lookup
API calls produce very similar output which is explained in this section.
There is one section for each format. The format correspond to what was
selected via the format parameter.

JSON Copy Chapter

The JSON format returns an array of places (for search and lookup) or
a single place (for reverse) of the following format:

{
    "place_id": 100149,
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "osm_type": "node",
    "osm_id": "107775",
    "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
    "lat": "51.5073219",
    "lon": "-0.1276474",
    "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
    "class": "place",
    "type": "city",
    "importance": 0.9654895765402,
    "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
    "address": {
      "city": "London",
      "state_district": "Greater London",
      "state": "England",
      "ISO3166-2-lvl4": "GB-ENG",
      "postcode": "SW1A 2DU",
      "country": "United Kingdom",
      "country_code": "gb"
    },
    "extratags": {
      "capital": "yes",
      "website": "http://www.london.gov.uk",
      "wikidata": "Q84",
      "wikipedia": "en:London",
      "population": "8416535"
    }
  }

The possible fields are:

• place_id - reference to the Nominatim internal database ID (see notes)
• osm_type, osm_id - reference to the OSM object (see notes)
• boundingbox - area of corner coordinates (see notes)
• lat, lon - latitude and longitude of the centroid of the object
• display_name - full comma-separated address
• class, type - key and value of the main OSM tag
• importance - computed importance rank
• icon - link to class icon (if available)
• address - dictionary of address details (only with addressdetails=1,
  see notes)
• extratags - dictionary with additional useful tags like website or maxspeed
  (only with extratags=1)
• namedetails - dictionary with full list of available names including ref etc.
• geojson, svg, geotext, geokml - full geometry
  (only with the appropriate polygon_* parameter)
• entrances - array of objects representing tagged entrances for the object, or
  null if none are found (only with entrances=1)

JSONv2 Copy Chapter

This is the same as the JSON format with two changes:

• class renamed to category
• additional field place_rank with the search rank of the object

GeoJSON Copy Chapter

This format follows the RFC7946. Every feature includes
a bounding box (bbox).

The properties object has the following fields:

• place_id - reference to the Nominatim internal database ID (see notes)
• osm_type, osm_id - reference to the OSM object (see notes)
• category, type - key and value of the main OSM tag
• display_name - full comma-separated address
• place_rank - class search rank
• importance - computed importance rank
• icon - link to class icon (if available)
• address - dictionary of address details (only with addressdetails=1,
  see notes)
• extratags - dictionary with additional useful tags like website or maxspeed
  (only with extratags=1)
• namedetails - dictionary with full list of available names including ref etc.
• entrances - array of objects representing tagged entrances for the object, or
  null if none are found (only with entrances=1)

Use polygon_geojson to output the full geometry of the object instead
of the centroid.

GeocodeJSON Copy Chapter

The GeocodeJSON format follows the
GeocodeJSON spec 0.1.0.
The following feature attributes are implemented:

• osm_type, osm_id - reference to the OSM object (unofficial extension, see notes)
• type - the 'address level' of the object ('house', 'street', district, city,
  county, state, country, locality)
• osm_key- key of the main tag of the OSM object (e.g. boundary, highway, amenity)
• osm_value - value of the main tag of the OSM object (e.g. residential, restaurant)
• label - full comma-separated address
• name - localised name of the place
• housenumber, street, locality, district, postcode, city,
  county, state, country -
  provided when it can be determined from the address (only with addressdetails=1)
• admin - list of localised names of administrative boundaries (only with addressdetails=1)
• extra - dictionary with additional useful tags like website or maxspeed
  (only with extratags=1)
• entrances - array of objects representing tagged entrances for the object, or
  null if none are found (only with entrances=1)

Use polygon_geojson to output the full geometry of the object instead
of the centroid.

XML Copy Chapter

The XML response returns one or more place objects in slightly different
formats depending on the API call.

Reverse Copy Section

<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
                querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
  <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
          lat="48.9467562" lon="11.4038717"
          boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
       Bavaria, Germany
  </result>
  <addressparts>
     <state>Bavaria</state>
     <ISO3166-2-lvl4>DE-BY</ISO3166-2-lvl4>
     <country>Germany</country>
     <country_code>de</country_code>
  </addressparts>
  <extratags>
    <tag key="place" value="state"/>
    <tag key="wikidata" value="Q980"/>
    <tag key="wikipedia" value="de:Bayern"/>
    <tag key="population" value="12520000"/>
    <tag key="name:prefix" value="Freistaat"/>
  </extratags>
</reversegeocode>

The attributes of the outer reversegeocode element return generic information
about the query, including the time when the response was sent (in UTC),
attribution to OSM and the original querystring.

The place information can be found in the result element. The attributes of that element contain:

• place_id - reference to the Nominatim internal database ID (see notes)
• osm_type, osm_id - reference to the OSM object (see notes)
• ref - content of ref tag if it exists
• lat, lon - latitude and longitude of the centroid of the object
• boundingbox - comma-separated list of corner coordinates (see notes)

The full address of the result can be found in the content of the
result element as a comma-separated list.

Additional information requested with addressdetails=1, extratags=1,
namedetails=1, and entrances=1 can be found in extra elements.

Search and Lookup Copy Section

<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
               attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
               querystring="london" polygon="false" exclude_place_ids="N107775"
               more_url="https://nominatim.openstreetmap.org/search?q=london&addressdetails=1&extratags=1&exclude_place_ids=N107775&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3">
  <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"
         boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
         display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
         class="place" type="city" importance="0.9654895765402"
         icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
    <extratags>
      <tag key="capital" value="yes"/>
      <tag key="website" value="http://www.london.gov.uk"/>
      <tag key="wikidata" value="Q84"/>
      <tag key="wikipedia" value="en:London"/>
      <tag key="population" value="8416535"/>
    </extratags>
    <city>London</city>
    <state_district>Greater London</state_district>
    <state>England</state>
    <ISO3166-2-lvl4>GB-ENG</ISO3166-2-lvl4>
    <postcode>SW1A 2DU</postcode>
    <country>United Kingdom</country>
    <country_code>gb</country_code>
  </place>
</searchresults>

The attributes of the outer searchresults or lookupresults element return
generic information about the query:

• timestamp - UTC time when the response was sent
• attribution - OSM licensing information
• querystring - original query
• polygon - true when extra geometry information was requested
• exclude_place_ids - IDs of places that should be ignored in a follow-up request (OSM IDs where possible, otherwise place_ids)
• more_url - search call that will yield additional results for the query
  just sent

The place information can be found in the place elements, of which there may
be more than one. The attributes of that element contain:

• place_id - reference to the Nominatim internal database ID (see notes)
• osm_type, osm_id - reference to the OSM object (see notes)
• ref - content of ref tag if it exists
• lat, lon - latitude and longitude of the centroid of the object
• boundingbox - comma-separated list of corner coordinates (see notes)
• place_rank - class search rank
• address_rank - place address rank
• display_name - full comma-separated address
• class, type - key and value of the main OSM tag
• importance - computed importance rank
• icon - link to class icon (if available)

When addressdetails=1 is requested, the localised address parts appear
as subelements with the type of the address part.

Additional information requested with extratags=1, namedetails=1, and
entrances=1 can be found in extra elements as sub-element of extratags,
namedetails, and entrances respectively.

Debug output Copy Chapter

Adding debug=1 to a query to the /search, /reverse,
/lookup or /details endpoint switches the output to
an HTML page with assorted developer debug information: how Nominatim parsed,
understood and executed its database searches.

Debug output is disabled by default. It is only available when the server
administrator has enabled
NOMINATIM_SERVE_DEBUG_OUTPUT.

Notes on field values Copy Chapter

place_id is not a persistent id Copy Section

The place_id is an internal identifier that is assigned data is imported
into a Nominatim database. The same OSM object will have a different value
on another server. It may even change its ID on the same server when it is
removed and reimported while updating the database with fresh OSM data.
It is thus not useful to treat it as permanent for later use.

The combination osm_type+osm_id is slightly better but remember in
OpenStreetMap mappers can delete, split, recreate places (and those
get a new osm_id), there is no link between those old and new ids.
Places can also change their meaning without changing their osm_id,
e.g. when a restaurant is retagged as supermarket. For a more in-depth
discussion see Permanent ID.

If you need an ID that is consistent over multiple installations of Nominatim,
then you should use the combination of osm_type+osm_id+class.

OSM reference Copy Section

Nominatim may sometimes return special objects that do not correspond directly
to an object in OpenStreetMap. These are:

• Postcodes. Nominatim returns an postcode point created from all mapped
  postcodes of the same name. The class and type of these object is place=postcdode.
  No osm_type and osm_id are included in the result.
• Housenumber interpolations. Nominatim returns a single interpolated
  housenumber from the interpolation way. The class and type are place=house
  and osm_type and osm_id correspond to the interpolation way in OSM.
• TIGER housenumber. Nominatim returns a single interpolated housenumber
  from the TIGER data. The class and type are place=house
  and osm_type and osm_id correspond to the street mentioned in the result.

Please note that the osm_type and osm_id returned may be changed in the
future. You should not expect to only find node, way and relation for
the type.

boundingbox Copy Section

Comma separated list of min latitude, max latitude, min longitude, max longitude.
The whole planet would be -90,90,-180,180.

Can be used to pan and center the map on the result, for example with leafletjs
mapping library
map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});

Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
essentially covering the entire planet
(see issue 184).

addressdetails Copy Section

Address details in the xml and json formats return a list of names together
with a designation label. Per default the following labels may appear:

• continent
• country, country_code
• region, state, state_district, county, ISO3166-2-lvl
• municipality, city, town, village
• city_district, district, borough, suburb, subdivision
• hamlet, croft, isolated_dwelling
• neighbourhood, allotments, quarter
• city_block, residential, farm, farmyard, industrial, commercial, retail
• road
• house_number, house_name
• emergency, historic, military, natural, landuse, place, railway,
  man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
  office, mountain_pass, shop, tourism, bridge, tunnel, waterway
• postcode

They roughly correspond to the classification of the OpenStreetMap data
according to either the place tag or the main key of the object.

entrances Copy Section

Entrance details in the xml and json formats return the latitude and longitude
of the entrance, the osm node ID, the type of
entrance, and any extra tags
associated with the entrance node.

• osm_id
• type
• lat
• lon
• extratags

They roughly correspond to the classification of the OpenStreetMap data
according to either the place tag or the main key of the object.

Example

JSON

https://nominatim.openstreetmap.org/details?osmtype=W&osmid=32619803&entrances=1&format=json

{
  "place_id": 124325848,
  "parent_place_id": 123936289,
  "osm_type": "W",
  "osm_id": 32619803,
  "category": "shop",
  "type": "supermarket",
  "admin_level": 15,
  "localname": "PENNY",
  ...
  "entrances": [
    {
      "osm_id": 1733488238,
      "type": "yes",
      "lat": "51.0466704",
      "lon": "12.8077106",
      "extratags": {
        "foot": "yes"
      }
    },
    {
      "osm_id": 1733488256,
      "type": "main",
      "lat": "51.0467197",
      "lon": "12.8078448",
      "extratags": {
        "foot": "yes"
      }
    },
    {
      "osm_id": 1733498087,
      "type": "exit",
      "lat": "51.0467081",
      "lon": "12.8078131",
      "extratags": {
        "foot": "yes"
      }
    },
    {
      "osm_id": 7914950851,
      "type": "service",
      "lat": "51.0468487",
      "lon": "12.8075876",
      "extratags": {
        "access": "delivery"
      }
    }
  ]
}

Api Reverse (`docs/api/Reverse.md`) Copy Section

Reverse Geocoding

Reverse geocoding generates an address from a coordinate given as
latitude and longitude.

How it works Copy Chapter

The reverse geocoding API does not exactly compute the address for the
coordinate it receives. It works by finding the closest suitable OSM object
and returning its address information. This may occasionally lead to
unexpected results.

First of all, Nominatim only includes OSM objects in
its index that are suitable for searching. Small, unnamed paths for example
are missing from the database and can therefore not be used for reverse
geocoding either.

The other issue to be aware of is that the closest OSM object may not always
have a similar enough address to the coordinate you were requesting. For
example, in dense city areas it may belong to a completely different street.

Endpoint Copy Chapter

The main format of the reverse API is

https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>

where lat and lon are latitude and longitude of a coordinate in WGS84
projection. The API returns exactly one result or an error when the coordinate
is in an area with no OSM data coverage.

!!! tip
The reverse API allows a lookup of object by coordinate. If you want
to look up an object by ID, use the Address Lookup API instead.

!!! danger "Deprecation warning"
The API can also be used with the URL
https://nominatim.openstreetmap.org/reverse.php. This is now deprecated
and will be removed in future versions.

Parameters Copy Chapter

This section lists additional parameters to further influence the output.

Output format Copy Section

See Place Output Formats for details on each format.

When given, then JSON output will be wrapped in a callback function with
the given name. See JSONP for more
information.

Only has an effect for JSON output formats.

Output details Copy Section

When set to 1, include a breakdown of the address into elements.
The exact content of the address breakdown depends on the output format.

!!! tip
If you are interested in a stable classification of address categories
(suburb, city, state, etc), have a look at the geocodejson format.
All other formats return classifications according to OSM tagging.
There is a much larger set of categories and they are not always consistent,
which makes them very hard to work with.

When set to 1, the response include any additional information in the result
that is available in the database, e.g. wikipedia link, opening hours.

When set to 1, include a full list of names for the result. These may include
language variants, older names, references and brand.

When set to 1, include the tagged entrances in the result.

Language of results Copy Section

Preferred language order for showing search results. This may either be
a simple comma-separated list of language codes or have the same format
as the "Accept-Language" HTTP header.

!!! tip
First-time users of Nominatim tend to be confused that they get different
results when using Nominatim in the browser versus in a command-line tool
like wget or curl. The command-line tools
usually don't send any Accept-Language header, prompting Nominatim
to show results in the local language. Browsers on the contrary always
send the currently chosen browser language.

Result restriction Copy Section

Level of detail required for the address. This is a number that
corresponds roughly to the zoom level used in XYZ tile sources in frameworks
like Leaflet.js, Openlayers etc.
In terms of address details the zoom levels are as follows:

The layer filter allows to select places by themes.

The address layer contains all places that make up an address:
address points with house numbers, streets, inhabited places (suburbs, villages,
cities, states etc.) and administrative boundaries.

The poi layer selects all point of interest. This includes classic points
of interest like restaurants, shops, hotels but also less obvious features
like recycling bins, guideposts or benches.

The railway layer includes railway infrastructure like tracks.
Note that in Nominatim's standard configuration, only very few railway
features are imported into the database.

The natural layer collects features like rivers, lakes and mountains while
the manmade layer functions as a catch-all for features not covered by the
other layers.

Polygon output Copy Section

Add the full geometry of the place to the result output. Output formats
in GeoJSON, KML, SVG or WKT are supported. Only one of these
options can be used at a time.

When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry.

Other Copy Section

If you are making large numbers of request please include an appropriate email
address to identify your requests. See Nominatim's
Usage Policy for more details.

Output special developer debug information instead of the normal result.
See Debug output for details.

Examples Copy Chapter

• https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1&layer=address

<reversegeocode timestamp="Fri, 06 Nov 09 16:33:54 +0000" querystring="...">
    <result place_id="1620612" osm_type="node" osm_id="452010817">
      135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom
    </result>
    <addressparts>
      <house_number>135</house_number>
      <road>Pilkington Avenue</road>
      <village>Wylde Green</village>
      <town>Sutton Coldfield</town>
      <city>City of Birmingham</city>
      <county>West Midlands (county)</county>
      <postcode>B72</postcode>
      <country>United Kingdom</country>
      <country_code>gb</country_code>
    </addressparts>
  </reversegeocode>

Example with `format=jsonv2`

• https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521&layer=address

{
  "place_id":"134140761",
  "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
  "osm_type":"way",
  "osm_id":"280940520",
  "lat":"-34.4391708",
  "lon":"-58.7064573",
  "place_rank":"26",
  "category":"highway",
  "type":"motorway",
  "importance":"0.1",
  "addresstype":"road",
  "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina",
  "name":"Autopista Pedro Eugenio Aramburu",
  "address":{
    "road":"Autopista Pedro Eugenio Aramburu",
    "village":"El Triángulo",
    "state_district":"Partido de Malvinas Argentinas",
    "state":"Buenos Aires",
    "postcode":"1.619",
    "country":"Argentina",
    "country_code":"ar"
  },
  "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"]
}

Example with `format=geojson`

• https://nominatim.openstreetmap.org/reverse?format=geojson&lat=44.50155&lon=11.33989&layer=address

{
  "type": "FeatureCollection",
  "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "place_id": 77292420,
        "osm_type": "node",
        "osm_id": 1704756187,
        "place_rank": 30,
        "category": "place",
        "type": "house",
        "importance": 7.805828946359988e-5,
        "addresstype": "place",
        "name": "",
        "display_name": "71, Via Guglielmo Marconi, Pioggia, Marconi, Porto-Saragozza, Bologna, Emilia-Romagna, 40122, Italy",
        "address": {
          "house_number": "71",
          "road": "Via Guglielmo Marconi",
          "neighbourhood": "Pioggia",
          "suburb": "Marconi",
          "city": "Bologna",
          "county": "Bologna",
          "ISO3166-2-lvl6": "IT-BO",
          "state": "Emilia-Romagna",
          "ISO3166-2-lvl4": "IT-45",
          "postcode": "40122",
          "country": "Italy",
          "country_code": "it"
        }
      },
      "bbox": [
        11.3397676,
        44.5014307,
        11.3399676,
        44.5016307
      ],
      "geometry": {
        "type": "Point",
        "coordinates": [
          11.3398676,
          44.5015307
        ]
      }
    }
  ]
}

Example with `format=geocodejson`

https://nominatim.openstreetmap.org/reverse?format=geocodejson&lat=60.2299&lon=11.1663&layer=address

{
  "type": "FeatureCollection",
  "geocoding": {
    "version": "0.1.0",
    "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "licence": "ODbL",
    "query": "60.229917843587,11.16630979382"
  },
  "features": {
    "type": "Feature",
    "properties": {
      "geocoding": {
        "place_id": "42700574",
        "osm_type": "node",
        "osm_id": "3110596255",
        "type": "house",
        "accuracy": 0,
        "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway",
        "name": null,
        "housenumber": "1",
        "street": "Løvenbergvegen",
        "postcode": "2054",
        "county": "Akershus",
        "country": "Norway",
        "admin": {
          "level7": "Ullensaker",
          "level4": "Akershus",
          "level2": "Norway"
        }
      }
    },
    "geometry": {
      "type": "Point",
      "coordinates": [
        11.1658572,
        60.2301296
      ]
    }
  }
}

Api Search (`docs/api/Search.md`) Copy Section

Search queries

The search API allows you to look up a location from a textual description
or address. Nominatim supports structured and free-form search queries.

The search query may also contain
special phrases
which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => amenity=pub).
This can be used to narrow down the kind of objects to be returned.

!!! note
Special phrases are not suitable to query all objects of a certain type in an
area. Nominatim will always just return a collection of the best matches. To
download OSM data by object type, use the Overpass API.

Endpoint Copy Chapter

The search API has the following format:

https://nominatim.openstreetmap.org/search?<params>

!!! danger "Deprecation warning"
The API can also be used with the URL
https://nominatim.openstreetmap.org/search.php. This is now deprecated
and will be removed in future versions.

The query term can be given in two different forms: free-form or structured.

Free-form query Copy Section

In this form, the query can be unstructured.
Free-form queries are processed first left-to-right and then right-to-left if that fails. So you may search for
pilkington avenue, birmingham as well as for
birmingham, pilkington avenue.
Commas are optional, but improve performance by reducing the complexity of the search.

The free-form may also contain special phrases to describe the type of
place to be returned or a coordinate to search close to a position.

Structured query Copy Section

The structured form of the search query allows to lookup up an address
that is already split into its components. Each parameter represents a field
of the address. All parameters are optional. You should only use the ones
that are relevant for the address you want to geocode.

!!! Attention
Cannot be combined with the q=<query> parameter. Newer versions of
the API will return an error if you do so. Older versions simply return
unexpected results.

Parameters Copy Chapter

The following parameters can be used to further restrict the search and
change the output. They are usable for both forms of the search query.

Output format Copy Section

See Place Output Formats for details on each format.

!!! note
The Nominatim service at
https://nominatim.openstreetmap.org
has a different default behaviour for historical reasons. When the
format parameter is omitted, the request will be forwarded to the Web UI.

When given, then JSON output will be wrapped in a callback function with
the given name. See JSONP for more
information.

Only has an effect for JSON output formats.

Limit the maximum number of returned results. Cannot be more than 40.
Nominatim may decide to return less results than given, if additional
results do not sufficiently match the query.

Output details Copy Section

When set to 1, include a breakdown of the address into elements.
The exact content of the address breakdown depends on the output format.

!!! tip
If you are interested in a stable classification of address categories
(suburb, city, state, etc), have a look at the geocodejson format.
All other formats return classifications according to OSM tagging.
There is a much larger set of categories and they are not always consistent,
which makes them very hard to work with.

When set to 1, the response include any additional information in the result
that is available in the database, e.g. wikipedia link, opening hours.

When set to 1, include a full list of names for the result. These may include
language variants, older names, references and brand.

When set to 1, include the tagged entrances in the result.

Language of results Copy Section

Preferred language order for showing search results. This may either be
a simple comma-separated list of language codes or have the same format
as the "Accept-Language" HTTP header.

!!! tip
First-time users of Nominatim tend to be confused that they get different
results when using Nominatim in the browser versus in a command-line tool
like wget or curl. The command-line tools
usually don't send any Accept-Language header, prompting Nominatim
to show results in the local language. Browsers on the contrary always
send the currently chosen browser language.

Result restriction Copy Section

There are two ways to influence the results. Filters exclude certain
kinds of results completely. Boost parameters only change the order of the
results and thus give a preference to some results over others.

Filter that limits the search results to one or more countries.
The country code must be the
ISO 3166-1alpha2 code
of the country, e.g. gb for the United Kingdom, de for Germany.

Each place in Nominatim is assigned to one country code based
on OSM country boundaries. In rare cases a place may not be in any country
at all, for example, when it is in international waters. These places are
also excluded when the filter is set.

!!! Note
This parameter should not be confused with the 'country' parameter of
the structured query. The 'country' parameter contains a search term
and will be handled with some fuzziness. The countrycodes parameter
is a hard filter and as such should be preferred. Having both parameters
in the same query will work. If the parameters contradict each other,
the search will come up empty.

The layer filter allows to select places by themes.

The address layer contains all places that make up an address:
address points with house numbers, streets, inhabited places (suburbs, villages,
cities, states tec.) and administrative boundaries.

The poi layer selects all point of interest. This includes classic POIs like
restaurants, shops, hotels but also less obvious features like recycling bins,
guideposts or benches.

The railway layer includes railway infrastructure like tracks.
Note that in Nominatim's standard configuration, only very few railway
features are imported into the database.

The natural layer collects features like rivers, lakes and mountains while
the manmade layer functions as a catch-all for features not covered by the
other layers.

The featureType allows to have a more fine-grained selection for places
from the address layer. Results can be restricted to places that make up
the 'state', 'country' or 'city' part of an address. A featureType of
settlement selects any human inhabited feature from 'state' down to
'neighbourhood'.

When featureType is set, then results are automatically restricted
to the address layer (see above).

!!! tip
Instead of using the featureType filters country, state or city,
you can also use a structured query without the finer-grained parameters
amenity or street.

Filters that select or drop results by category. A category describes what kind
of place an object is. It has the form osm.<key>.<value>, taken from a main
OSM tag of the object, for example osm.amenity.restaurant. An object has one
category for every main tag it carries. A place tagged with tourism=hotel and
amenity=restaurant therefore has the categories osm.tourism.hotel and
osm.amenity.restaurant.

Categories are hierarchical and a filter matches the category itself as well as
all its descendants. include=osm.amenity selects restaurants, cafes,
pharmacies and everything else carrying an amenity tag. A category must
consist of at least two labels separated by dots, so include=osm is rejected
with an error. Only letters, digits and underscores may appear in a label.
Hyphens of the original OSM tag are replaced with underscores when the category
is created, so shop=car-repair is selected with
include=osm.shop.car_repair.

Both parameters may be repeated. Note that a comma and a repetition combine
the categories in different ways:

!!! note
Categories are only used for filtering, they are never part of the output.
The category/class and type fields of a result contain the single
main tag that Nominatim uses to classify the place. That is only one of
the categories the place may have.

!!! note
A place without any category cannot satisfy include. Postcodes, address
interpolations, TIGER housenumbers and countries returned from
Nominatim's built-in country-list fallback (used when no matching OSM
boundary was found) therefore disappear from the results as soon as
include is used. exclude has no effect on them. Countries backed by
an OSM boundary keep their usual category and are filtered normally.

If you do not want certain OSM objects to appear in the search
result, give a comma separated list of the ids you want to skip.

Each entry may be one of:

• a Nominatim internal place_id (for example 125279639)
• an OSM object reference in the form <osm_type><osm_id> where <osm_type> is one of N (node), W (way) or R (relation), for example N107775
• a stable postcode reference in the form P<country_code>:, for example Pus:94110 or Pgb:EH4_7EA

Usage of OSM IDs is recommended because they are server independent. Stable postcode refs should be used for artificial postcode results without an OSM object reference. In postcode refs, spaces are replaced with underscores. place_ids are still required for results without either kind of stable reference (for example, countries). When a street is excluded via its OSM ID, then interpolations and TIGER data derived from that street are excluded as well.

This can be used to retrieve additional search results. For example, if a
previous query only returned a few results, then including those here would
cause the search to return other, less accurate, matches (if possible).

Boost parameter which focuses the search on the given area.
Any two corner points of the box are accepted as long as they make a proper
box. x is longitude, y is latitude.

When set to 1, then it turns the 'viewbox' parameter (see above) into
a filter parameter, excluding any results outside the viewbox.

When bounded=1 is given and the viewbox is small enough, then an amenity-only
search is allowed. Give the special keyword for the amenity in square
brackets, e.g. [pub] and a selection of objects of this type is returned.
There is no guarantee that the result returns all objects in the area.

Polygon output Copy Section

Add the full geometry of the place to the result output. Output formats
in GeoJSON, KML, SVG or WKT are supported. Only one of these
options can be used at a time.

When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry.

Other Copy Section

If you are making large numbers of request please include an appropriate email
address to identify your requests. See Nominatim's
Usage Policy for more details.

Sometimes you have several objects in OSM identifying the same place or
object in reality. The simplest case is a street being split into many
different OSM ways due to different characteristics. Nominatim will
attempt to detect such duplicates and only return one match. Setting
this parameter to 0 disables this deduplication mechanism and
ensures that all results are returned.

Output special developer debug information instead of the normal result.
See Debug output for details.

Examples Copy Chapter

XML with KML polygon

• https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_kml=1&addressdetails=1

/* Detailed source-code truncated for AI context efficiency. */

JSON with SVG polygon

https://nominatim.openstreetmap.org/search?q=Unter%20den%20Linden%201%20Berlin&format=json&addressdetails=1&limit=1&polygon_svg=1

[
  {
    "address": {
      "ISO3166-2-lvl4": "DE-BE",
      "borough": "Mitte",
      "city": "Berlin",
      "country": "Deutschland",
      "country_code": "de",
      "historic": "Kommandantenhaus",
      "house_number": "1",
      "neighbourhood": "Friedrichswerder",
      "postcode": "10117",
      "road": "Unter den Linden",
      "suburb": "Mitte"
    },
    "boundingbox": [
      "52.5170798",
      "52.5173311",
      "13.3975116",
      "13.3981577"
    ],
    "class": "historic",
    "display_name": "Kommandantenhaus, 1, Unter den Linden, Friedrichswerder, Mitte, Berlin, 10117, Deutschland",
    "importance": 0.8135042058306902,
    "lat": "52.51720765",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "lon": "13.397834399325466",
    "osm_id": 15976890,
    "osm_type": "way",
    "place_id": 108681845,
    "svg": "M 13.3975116 -52.5172905 L 13.397549 -52.5170798 13.397715 -52.5170906 13.3977122 -52.5171064 13.3977392 -52.5171086 13.3977417 -52.5170924 13.3979655 -52.5171069 13.3979623 -52.5171233 13.3979893 -52.5171248 13.3979922 -52.5171093 13.3981577 -52.5171203 13.398121 -52.5173311 13.3978115 -52.5173103 Z",
    "type": "house"
  }
]

JSON with address details

https://nominatim.openstreetmap.org/search?addressdetails=1&q=bakery+in+berlin+wedding&format=jsonv2&limit=1

[
  {
    "address": {
      "ISO3166-2-lvl4": "DE-BE",
      "borough": "Mitte",
      "city": "Berlin",
      "country": "Deutschland",
      "country_code": "de",
      "neighbourhood": "Sprengelkiez",
      "postcode": "13347",
      "road": "Lindower Straße",
      "shop": "Ditsch",
      "suburb": "Wedding"
    },
    "addresstype": "shop",
    "boundingbox": [
      "52.5427201",
      "52.5427654",
      "13.3668619",
      "13.3669442"
    ],
    "category": "shop",
    "display_name": "Ditsch, Lindower Straße, Sprengelkiez, Wedding, Mitte, Berlin, 13347, Deutschland",
    "importance": 9.99999999995449e-06,
    "lat": "52.54274275",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
    "lon": "13.36690305710228",
    "name": "Ditsch",
    "osm_id": 437595031,
    "osm_type": "way",
    "place_id": 204751033,
    "place_rank": 30,
    "type": "bakery"
  }
]

GeoJSON

https://nominatim.openstreetmap.org/search?q=17+Strada+Pictor+Alexandru+Romano%2C+Bukarest&format=geojson

{
  "type": "FeatureCollection",
  "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "place_id": "35811445",
        "osm_type": "node",
        "osm_id": "2846295644",
        "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania",
        "place_rank": "30",
        "category": "place",
        "type": "house",
        "importance": 0.62025
      },
      "bbox": [
        26.1156689,
        44.4354754,
        26.1157689,
        44.4355754
      ],
      "geometry": {
        "type": "Point",
        "coordinates": [
          26.1157189,
          44.4355254
        ]
      }
    }
  ]
}

GeocodeJSON

https://nominatim.openstreetmap.org/search?q=%CE%91%CE%B3%CE%AF%CE%B1+%CE%A4%CF%81%CE%B9%CE%AC%CE%B4%CE%B1%2C+%CE%91%CE%B4%CF%89%CE%BD%CE%B9%CE%B4%CE%BF%CF%82%2C+Athens%2C+Greece&format=geocodejson

{
  "type": "FeatureCollection",
  "geocoding": {
    "version": "0.1.0",
    "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "licence": "ODbL",
    "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece"
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "geocoding": {
          "type": "place_of_worship",
          "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece",
          "name": "Αγία Τριάδα",
          "admin": null
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          23.72949633941,
          38.0051697
        ]
      }
    }
  ]
}

Api Status (`docs/api/Status.md`) Copy Section

Status

Report on the state of the service and database. Useful for checking if the
service is up and running. The JSON output also reports
when the database was last updated.

Endpoint Copy Chapter

The status API has the following format:

https://nominatim.openstreetmap.org/status

!!! danger "Deprecation warning"
The API can also be used with the URL
https://nominatim.openstreetmap.org/status.php. This is now deprecated
and will be removed in future versions.

Parameters Copy Chapter

The status endpoint takes a single optional parameter:

Selects the output format. See below.

Output Copy Chapter

Text format

When everything is okay, a status code 200 is returned and a simple message: OK

On error it will return HTTP status code 500 and print a detailed error message, e.g.
ERROR: Database connection failed.

JSON format

Always returns a HTTP code 200, when the status call could be executed.

On success a JSON dictionary with the following structure is returned:

{
      "status": 0,
      "message": "OK",
      "data_updated": "2020-05-04T14:47:00+00:00",
      "software_version": "3.6.0-0",
      "database_version": "3.6.0-0"
  }

The software_version field contains the version of Nominatim used to serve
the API. The database_version field contains the version of the data format
in the database.

On error will return a shorter JSON dictionary with the error message
and status only, e.g.

{
       "status": 700,
       "message": "Database connection failed"
   }

Customize Country Settings (`docs/customize/Country-Settings.md`) Copy Section

Customizing Per-Country Data

Whenever an OSM is imported into Nominatim, the object is first assigned
a country. Nominatim can use this information to adapt various aspects of
the address computation to the local customs of the country. This section
explains how country assignment works and the principal per-country
localizations.

Country assignment Copy Chapter

Countries are assigned on the basis of country data from the OpenStreetMap
input data itself. Countries are expected to be tagged according to the
administrative boundary schema:
a OSM relation with boundary=administrative and admin_level=2. Nominatim
uses the country code to distinguish the countries.

If there is no country data available for a point, then Nominatim uses the
fallback data imported from data/country_osm_grid.sql.gz. This was computed
from OSM data as well but is guaranteed to cover all countries.

Some OSM objects may also be located outside any country, for example a buoy
in the middle of the ocean. These object do not get any country assigned and
get a default treatment when it comes to localized handling of data.

Per-country settings Copy Chapter

Global country settings Copy Section

The main place to configure settings per country is the file
settings/country_settings.yaml. This file has one section per country that
is recognised by Nominatim. Each section is tagged with the country code
(in lower case) and contains the different localization information. Only
countries which are listed in this file are taken into account for computations.

For example, the section for Andorra looks like this:

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

The individual settings are described below.

`partition`

Nominatim internally splits the data into multiple tables to improve
performance. The partition number tells Nominatim into which table to put
the country. This is purely internal management and has no effect on the
output data.

The default is to have one partition per country.

`languages`

A comma-separated list of ISO-639 language codes of default languages in the
country. These are the languages used in name tags without a language suffix.
Note that this is not necessarily the same as the list of official languages
in the country. There may be officially recognised languages in a country
which are only ever used in name tags with the appropriate language suffixes.
Conversely, a non-official language may appear a lot in the name tags, for
example when used as an unofficial Lingua Franca.

List the languages in order of frequency of appearance with the most frequently
used language first. It is not recommended to add languages when there are only
very few occurrences.

If only one language is listed, then Nominatim will 'auto-complete' the
language of names without an explicit language-suffix.

`names`

List of names of the country and its translations. These names are used as
a baseline. It is always possible to search countries by the given names, no
matter what other names are in the OSM data. They are also used as a fallback
when a needed translation is not available.

!!! Note
The list of names per country is currently fairly large because Nominatim
supports translations in many languages per default. That is why the
name lists have been separated out into extra files. You can find the
name lists in the file settings/country-names/<country code>.yaml.
The names section in the main country settings file only refers to these
files via the special !include directive.

`postcode`

Describes the format of the postcode that is in use in the country.

When a country has no official postcodes, set this to no. Example:

ae:
    postcode: no

When a country has a postcode, you need to state the postcode pattern and
the default output format. Example:

bm:
    postcode:
      pattern: "(ll)[ -]?(dd)"
      output: \1 \2

The pattern is a regular expression that describes the possible formats
accepted as a postcode. The pattern follows the standard syntax for
regular expressions in Python
with two extra shortcuts: d is a shortcut for a single digit([0-9])
and l for a single ASCII letter ([A-Z]).

Use match groups to indicate groups in the postcode that may optionally be
separated with a space or a hyphen.

For example, the postcode for Bermuda above always consists of two letters
and two digits. They may optionally be separated by a space or hyphen. That
means that Nominatim will consider AB56, AB 56 and AB-56 spelling variants
for one and the same postcode.

Never add the country code in front of the postcode pattern. Nominatim will
automatically accept variants with a country code prefix for all postcodes.

The output field is an optional field that describes what the canonical
spelling of the postcode should be. The format is the
regular expression expand syntax referring back to the bracket groups in the pattern.

Most simple postcodes only have one spelling variant. In that case, the
output can be omitted. The postcode will simply be used as is.

In the Bermuda example above, the canonical spelling would be to have a space
between letters and digits.

!!! Warning
When your postcode pattern covers multiple variants of the postcode, then
you must explicitly state the canonical output or Nominatim will not
handle the variations correctly.

`sanitizers`

Defines Sanitizers which should only applied to places
within the given country. Country-specific sanitizers are executed after
the general sanitizers have run.

Other country-specific configuration Copy Section

There are some other configuration files where you can set localized settings
according to the assigned country. These are:

• Place ranking configuration

Please see the linked documentation sections for more information.

Customize Import Styles (`docs/customize/Import-Styles.md`) Copy Section

Configuring the Import of OSM data

In the very first step of a Nominatim import, OSM data is loaded into the
database. Nominatim uses osm2pgsql for this task.
It comes with a flex style
specifically tailored to filter and convert OSM data into Nominatim's
internal data representation. Nominatim ships with a few preset
configurations for this import, each results in a geocoding database of
different detail. The
Import section explains
these default configurations in detail.

If you want to have more control over which OSM data is added to the database,
you can also create your own custom style. Create a new lua style file, put it
into your project directory and then set NOMINATIM_IMPORT_STYLE to the name
of the file. Custom style files can be used to modify the existing preset
configurations or to implement your own configuration from scratch.

The remainder of the page describes how the flex style works and how to
customize it.

The `flex-base` lua module Copy Chapter

The core of Nominatim's flex import configuration is the flex-base module.
It defines the table layout used by Nominatim and provides standard
implementations for the import callbacks that help with customizing
how OSM tags are used by Nominatim.

Every custom style must include this module to make sure that the correct
tables are created. Thus start your custom style as follows:

local flex = require('flex-base')

Using preset configurations Copy Section

If you want to start with one of the existing presets, then you can import
its settings using the load_topic() function:

local flex = require('flex-base')

flex.load_topic('streets')

The load_topic function takes an optional second configuration
parameter. The available options are explained in the
themepark section.

Available topics are: admin, street, address, full. These topic
correspond to the import styles
you can choose during import. To start with the 'extratags' style, use the
full topic with the appropriate config parameter:

flex.load_topic('full', {with_extratags = true})

!!! note
You can also directly import the preset style files, e.g.
local flex = require('import-street'). It is not possible to
set extra configuration this way.

How processing works Copy Section

When Nominatim processes an OSM object, it looks for four kinds of tags:
The main tags classify what kind of place the OSM object represents. One
OSM object can have more than one main tag. All of them end up in the same
database entry, which gets one category per main tag. Name tags represent
searchable names of the place. Address tags are used to compute the address
information of the place. Address tags are used for searching and for creating
a display name of the place.
Extra tags are any tags that are not directly related to search but
contain interesting additional information. These are just saved in the database
and may be returned with the result on request.

!!! danger
Some of the extra tags are used by Nominatim to better
classify the place. These tags will always be added, independent of
any settings in the style.

Configuring the style means deciding which key and/or key/value is used
as which kind of tag.

Categories Copy Section

A category is derived from a main tag and written as osm.<key>.<value>.
An object tagged with tourism=hotel and amenity=restaurant therefore gets
the categories osm.tourism.hotel and osm.amenity.restaurant. Categories are
hierarchical and can be used to filter search results, see the
search API.

A key or value may only be turned into a category label if it consists
solely of ASCII letters (upper- or lower-case), digits, underscore and
hyphen; hyphens are then replaced with underscores, so the resulting label
itself never contains one. A main tag whose value contains any other
character gets the category osm.<key>.yes. When the key itself contains
such a character, then no category is created for the tag at all.

Nominatim also needs a single main tag to classify and rank the place. It is
saved as the class and type of the place and returned in the
category/type fields of a result. When an object has more than one main
tag, then the alphabetically first key/value pair wins. Tags classified as
fallback (see below) never win against another main tag.

Changing the recognized tags Copy Chapter

The flex style offers a number of functions to set the classification of
each OSM tag. Most of these functions can also take a preset string instead
of a tag description. These presets describe common configurations that
are also used in the definition of the predefined styles. This section
lists the configuration functions and the accepted presets.

Key match lists

Some of the following functions take key match lists. These lists can
contain three kinds of strings to match against tag keys:
A string that ends in an asterisk * is a prefix match and accordingly matches
against any key that starts with the given string (minus the *).
A suffix match can be defined similarly with a string that starts with a *.
Any other string is matched exactly against tag keys.

Main tags Copy Section

set/modify_main_tags() allow to define which tags are used as main tags. It
takes a lua table parameter which defines for keys and key/value
combinations, how they are classified.

The following classifications are recognized:

Each key in the table parameter defines an OSM tag key. The value may
be directly a classification as described above. Then the tag will
be considered a main tag for any possible value that is not further defined.
To further restrict which values are acceptable, give a table with the
permitted values and their kind of main tag. If the table contains a simple
value without key, then this is used as default for values that are not listed.

set_main_tags() will completely replace the current main tag configuration
with the new configuration. modify_main_tags() will merge the new
configuration with the existing one. Merging is done at value level.
For example, when the current setting is highway = {'always', primary = 'named'},
then set_main_tags{highway = 'delete'} will result in a rule
highway = {'delete', primary = 'named'}.

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

flex.set_main_tags{
    boundary = {administrative = 'named'},
    highway = {'always', street_lamp = 'named', no = 'delete'},
    landuse = 'fallback'
}
```

In this example an object with a `boundary` tag will only be included
when it has a value of `administrative`. Objects with `highway` tags are
always included with two exceptions: the troll tag `highway=no` is
deleted on the spot. And when the value is `street_lamp` then the object
must also have a name, to be included. Finally, if a `landuse` tag is
present on a named object then it is used independently of the concrete
value, but it only determines the class and type of the place when neither
a boundary nor a highway tag was found.

Presets

Advanced main tag handling

The groups described above are in fact only a preset for a filtering function
that is used to make the final decision how a pre-selected main tag is entered
into Nominatim's internal table. To further customize handling you may also
supply your own filtering function.

The function takes up to three parameters: a Place object of the object
being processed, the key of the main tag and the value of the main tag.
The function may return one of three values:

• nil or false causes the entry to be ignored
• the Place object causes the place to be added as is
• `Place.copy(names=..., address=..., extratags=...) causes the
  place to be enter into the database but with name/address/extratags
  set to the given different values.

The Place object has some read-only values that can be used to determine
the handling:

• object is the original OSM object data handed in by osm2pgsql
• admin_level is the content of the admin_level tag, parsed into an integer and normalized to a value between 0 and 15
• has_name is a boolean indicating if the object has a primary name tag
• names is a table with the collected list of name tags
• address is a table with the collected list of address tags
• extratags is a table with the collected list of additional tags to save

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

flex.add_topic('street')

local function no_sidewalks(place, k, v)
    if place.object.tags.footway == 'sidewalk' then
        return false
    end

    -- default behaviour is to have all footways
    return place
end

flex.modify_main_tags(highway = {'footway' = no_sidewalks}
```
This script adds a custom handler for `highway=footway`. It only includes
them in the database, when the object doesn't have a tag `footway=sidewalk`
indicating that it is just part of a larger street which should already
be indexed. Note that it is not necessary to check the key and value
of the main tag because the function is only used for the specific
main tag.

Ignored tags Copy Section

The function ignore_keys() sets the delete classification for keys.
This function takes a key match list so that it is possible to exclude
groups of keys.

Note that full matches always take precedence over suffix matches, which
in turn take precedence over prefix matches.

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

flex.add_topic('admin')
flex.ignore_keys{'old_name', 'old_name:*'}
```

This example uses the `admin` preset with the exception that names
that are no longer are in current use, are ignored.

Presets

Tags for `extratags` Copy Section

The function add_for_extratags() sets the extra classification for keys.
This function takes a
key match list so that it is possible to move groups of keys to extratags.

Note that full matches always take precedence over suffix matches, which
in turn take precedence over prefix matches.

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

flex.add_topic('street')
flex.add_for_extratags{'surface', 'access', 'vehicle', 'maxspeed'}
```

This example uses the `street` preset but adds a couple of tags that
are of interest about the condition of the street.

Presets

Accepts all presets from ignored tags.

General pre-filtering Copy Section

(deprecated) set_prefilters() allows to set the delete and extra
classification for main tags.

This function removes all previously set main tags with delete and extra
classification and then adds the newly defined tags.

set_prefilters() takes a table with four optional fields:

• delete_keys is a key match list for tags that should be deleted
• delete_tags contains a table of tag keys pointing to a list of tag
  values. Tags with matching key/value pairs are deleted.
• extra_keys is a key match list for tags which should be saved into
  extratags
• extra_tags contains a table of tag keys pointing to a list of tag
  values. Tags with matching key/value pairs are moved to extratags.

!!! danger "Deprecation warning"
Use of this function should be replaced with modify_main_tags() to
set the data from delete_tags and extra_tags, with ignore_keys()
for the delete_keys parameter and with add_for_extratags() for the
extra_keys parameter.

Name tags Copy Section

set/modify_name_tags() allow to define the tags used for naming places. Name tags
can only be selected by their keys. The import script distinguishes
between primary and auxiliary names. A primary name is the given name of
a place. Having a primary name makes a place named. This is important
for main tags that are only included when a name is present. Auxiliary names
are identifiers like references. They may be searched for but should not
be included on their own.

The functions take a table with two optional fields main and extra.
They take key match lists for primary and auxiliary names respectively.
A third field house can contain tags for names that appear in place of
house numbers in addresses. This field can only contain complete key names.
'house tags' are special in that they cause the OSM object to be added to
the database independently of the presence of other main tags.

set_name_tags() overwrites the current configuration, while
modify_name_tags() replaces the fields that are given. (Be aware that
the fields are replaced as a whole. main = {'foo_name'} will cause
foo_name to become the only recognized primary name. Any previously
defined primary names are forgotten.)

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

flex.set_main_tags{highway = {traffic_light = 'named'}}
flex.set_name_tags{main = {'name', 'name:*'},
                   extra = {'ref'}
                  }
```

This example creates a search index over traffic lights but will
only include those that have a common name and not those which just
have some reference ID from the city.

Presets

Address tags Copy Section

set/modify_address_tags() defines the tags that will be used to build
up the address of an object. Address tags can only be chosen by their key.

The functions take a table with arbitrary fields, each defining
a key list or key match list. Some fields have a special meaning:

set_address_tags() overwrites the current configuration, while
modify_address_tags() replaces the fields that are given. (Be aware that
the fields are replaced as a whole.)

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

flex.set_address_tags{
    main = {'addr:housenumber'},
    extra = {'addr:*'},
    postcode = {'postal_code', 'postcode', 'addr:postcode'},
    country = {'country_code', 'ISO3166-1'}
}
```

In this example all tags which begin with `addr:` will be saved in
the address tag list. If one of the tags is `addr:housenumber`, the
object will fall back to be entered as a `place=house` in the database
unless there is another interested main tag to be found.

Tags with keys `country_code` and `ISO3166-1` are saved with their
value under `country` in the address tag list. The same thing happens
to postcodes, they will always be saved under the key `postcode` thus
normalizing the multitude of keys that are used in the OSM database.

Presets

Handling of unclassified tags Copy Section

set_unused_handling() defines what to do with tags that remain after all tags
have been classified using the functions above. There are two ways in
which the function can be used:

set_unused_handling(delete_keys = ..., delete_tags = ...) deletes all
keys that match the descriptions in the parameters and moves all remaining
tags into the extratags list.

set_unused_handling(extra_keys = ..., extra_tags = ...) moves all tags
matching the parameters into the extratags list and then deletes the remaining
tags. For the format of the parameters see the description in set_prefilters()
above.

When no special handling is set, then unused tags will be discarded with one
exception: place tags are kept in extratags for administrative boundaries.
When using a custom setting, you should also make sure that the place tag
is added for extratags.

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

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

In this example all remaining tags except those beginning with `tiger:`
are moved to the extratags list. Note that it is not possible to
already delete the tiger tags with `set_prefilters()` because that
would remove tiger:county before the address tags are processed.

Filling additional tables Copy Chapter

Most of the OSM objects are saved in the main place table for further
processing. In addition to that, there are some smaller tables that save
specialised information. The content of these tables can be customized as
well.

Entrance table Copy Section

The table place_entrance saves information about OSM nodes that represent
an entrance. This data is later mingled with buildings and other areas and
can be returned on request. The table
saves the type of entrance as well as a set of custom extra tags.

The function set_entrance_filter() can be used to customize the table's
content.

When called without any parameter, then filling the entrance table will be
disabled. When called with a preset name, the appropriate preset will be
applied.

To create a custom configuration, call the function
with a table with the following fields:

• main_tags is a list of tags that mark an entrance node. The value of the
  first tag found in the list will be used as the entrance type.
• extra_include is an optional list of tags to be added to the extratags
  for this entrance. When left out, all tags except for the ones defined
  in 'main_tags' will be included. To disable saving of extra tags, set
  this to the empty list.
• extra_exclude defines an optional list of tags to drop before including
  the remaining tags as extratags. Note that the tags defined in 'main_tags'
  will always be excluded, independently of this setting.

To have even more fine-grained control over the output, you can also hand
in a callback for processing entrance information. The callback function
receives a single parameter, the
osm2pgsql object.
This object itself must not be modified. The callback should return either
nil when the object is not an entrance. Or it returns a table with a
mandatory entrance field containing a string with the type of entrance
and an optional extratags field with a simple key-value table of extra
information.

Presets

Customizing osm2pgsql callbacks Copy Chapter

osm2pgsql expects the flex style to implement three callbacks, one process
function per OSM type. If you want to implement special handling for
certain OSM types, you can override the default implementations provided
by the flex-base module.

Enabling additional relation types Copy Section

OSM relations can represent very diverse
types of real-world objects. To
be able to process them correctly, Nominatim needs to understand how to
create a geometry for each type. By default, the script knows how to
process relations of type multipolygon, boundary and waterway. All
other relation types are ignored.

To add other types relations, set RELATION_TYPES for
the type to the kind of geometry that should be created. The following
kinds of geometries can be used:

• relation_as_multipolygon creates a (Multi)Polygon from the ways in
  the relation. If the ways do not form a valid area, then the object is
  silently discarded.
• relation_as_multiline creates a (Multi)LineString from the ways in
  the relations. Ways are combined as much as possible without any regards
  to their order in the relation.

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

flex.RELATION_TYPES['site'] = flex.relation_as_multipolygon
```

With this line relations of `type=site` will be included in the index
according to main tags found. This only works when the site relation
resolves to a valid area. Nodes in the site relation are not part of the
geometry.

Adding additional logic to processing functions Copy Section

The default processing functions are also exported by the flex-base module
as process_node, process_way and process_relation. These can be used
to implement your own processing functions with some additional processing
logic.

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

function osm2pgsql.process_relation(object)
    if object.tags.boundary ~= 'administrative' or object.tags.admin_level ~= '2' then
      flex.process_relation(object)
    end
end
```

This example discards all country-level boundaries and uses standard
handling for everything else. This can be useful if you want to use
your own custom country boundaries.

Customizing the main processing function Copy Section

!!! danger "Deprecation Warning"
The style used to allow overwriting the internal processing function
process_tags(). While this is currently still possible, it is no longer
encouraged and may stop working in future versions. The internal
Place class should now be considered read-only.

Using osm2pgsql-themepark Copy Chapter

The Nominatim osm2pgsql style is designed so that it can also be used as
a theme for osm2pgsql-themepark. This
makes it easy to combine Nominatim with other projects like
openstreetmap-carto
in the same database.

To set up one of the preset styles, simply include a topic with the same name:

local themepark = require('themepark')
themepark:add_topic('nominatim/address')

Themepark topics offer two configuration options:

• street_theme allows to choose one of the sub topics for streets:
  • default - include all major streets and named minor paths
  • car - include all streets physically usable by cars
  • all - include all major streets and minor paths
• with_extratags, when set to a truthy value, then tags that are
  not specifically used for address or naming are added to the
  extratags column

The customization functions described in the
Changing recognized tags section
are available from the theme. To access the theme you need to explicitly initialize it.

!!! Example
``` lua
local themepark = require('themepark')

themepark:add_topic('nominatim/full', {with_extratags = true})

local flex = themepark:init_theme('nominatim')

flex.modify_main_tags{'amenity' = {
                       'waste_basket' = 'delete'}
                  }
```
This example uses the full Nominatim configuration but disables
importing waste baskets.

You may also write a new configuration from scratch. Simply omit including
a Nominatim topic and only call the required customization functions.

Customizing the osm2pgsql processing functions as explained
above is not possible
when running under themepark. Instead include other topics that make the
necessary modifications or add an additional processor before including
the Nominatim topic.

!!! Example
``` lua
local themepark = require('themepark')

local function discard_country_boundaries(object)
    if object.tags.boundary == 'administrative' and object.tags.admin_level == '2' then
        return 'stop'
    end
end

themepark:add_proc('relation', discard_country_boundaries)
-- Order matters here. The topic needs to be added after the custom callback.
themepark:add_topic('nominatim/full', {with_extratags = true})
```
Discarding country-level boundaries when running under themepark.

Changing the style of existing databases Copy Chapter

There is usually no issue changing the style of a database that is already
imported and now kept up-to-date with change files. Just be aware that any
change in the style applies to updates only. If you want to change the data
that is already in the database, then a reimport is necessary.

Customize Importance (`docs/customize/Importance.md`) Copy Section

Importance Copy Chapter

Search requests can yield multiple results which match equally well with
the original query. In such case Nominatim needs to order the results
according to a different criterion: importance. This is a measure for how
likely it is that a user will search for a given place. This section explains
the sources Nominatim uses for computing importance of a place and how to
customize them.

How importance is computed Copy Section

The main value for importance is derived from page ranking values for Wikipedia
pages for a place. For places that do not have their own
Wikipedia page, a formula is used that derives a static importance from the
place's search rank.

In a second step, a secondary importance value is added which is meant to
represent how well-known the general area is where the place is located. It
functions as a tie-breaker between places with very similar primary
importance values.

nominatim.org has preprocessed importance tables for the
primary Wikipedia rankings
and for secondary importance
based on Wikipedia importance of the administrative areas.

The source code for creating these files is available in the Github projects
osm-search/wikipedia-wikidata
and
osm-search/secondary-importance.

Customizing secondary importance Copy Section

The secondary importance is implemented as a simple
Postgis raster table, where Nominatim
looks up the value for the coordinates of the centroid of a place. You can
provide your own secondary importance raster in form of an SQL file named
secondary_importance.sql.gz in your project directory.

The SQL file needs to drop and (re)create a table secondary_importance which
must as a minimum contain a column rast of type raster. The raster must
be in EPSG:4326 and contain 16bit unsigned ints
(`raster_constraint_pixel_types(rast) = '{16BUI}'). Any other columns in the
table will be ignored. You must furthermore create an index as follows:

CREATE INDEX ON secondary_importance USING gist(ST_ConvexHull(gist))

The following raster2pgsql command will create a table from a tiff file
that conforms to the requirements:

raster2pgsql -I -C -Y -d -t 128x128 input.tiff public.secondary_importance

Customize Postcodes (`docs/customize/Postcodes.md`) Copy Section

External postcode data

Nominatim creates a table of known postcode centroids and geometries during import.
This table is used for searches of postcodes and for adding postcodes to places where
the OSM data does not provide one. These postcode centroids are mainly computed
from the OSM data itself. In addition, Nominatim supports reading postcode information
from external files to supplement the postcodes that are missing in OSM.

Supported file formats Copy Chapter

Nominatim supports 2 data formats for external import:

JSONL format Copy Section

The JSONL format may contain the postcode data along with a POLYGON or MULTIPOLYGON geometry
of the postcode area. To enable external postcode support, put one file per country into
your project directory and name it <CC>_postcodes_geometry.<ext>. <CC> must be the
two-letter country code for which to apply the file. File type may be either .jsonl or
.jsonl.gz (gzip compressed). The file must be in UTF-8 encoding and contain one JSON object
per line with the following structure:

GeoJSON Feature

A standard RFC7946 GeoJSON Feature object.

• geometry: (required) A GeoJSON geometry (Polygon/MultiPolygon).
• properties: (required) An object containing:
  • postcode: (required) The postcode string.
  • lat, lon: (optional) Coordinates for the centroid. If not provided, the centroid
    is computed from the geometry.

CSV format Copy Section

To enable external postcode support, put one file per country into
your project directory and name it <CC>_postcodes.<ext>. <CC> must be the
two-letter country code for which to apply the file. File type may be either .csv or .csv.gz
(gzip compressed). The CSV file must use commas as a delimiter and have a header line. Nominatim
expects three columns to be present: postcode, lat and lon. All other columns are ignored.
lon and lat must describe the x and y coordinates of the postcode centroids in WGS84.

The postcode area is assumed to be in a buffer around the centroid (typically 5km).

Usage Copy Chapter

As a rule, the external postcode data should be put into the project directory
before starting the initial import. Still, you can add, remove and update the
external postcode data at any time. Simply run:

nominatim refresh --postcodes

to make the changes visible in your database. Be aware, however, that the changes
only have an immediate effect on searches for postcodes. Postcodes that were
added to places are only updated, when they are reindexed. That usually happens
only during replication updates.

Customize Query Preprocessing (`docs/customize/Query-Preprocessing.md`) Copy Section

Query preprocessing

The query preprocessing step allows to transform the incoming query before
it is processed by the tokenizer. This includes removing unrelated parts,
rephrasing and phrase tagging.

Configuration Copy Chapter

Query preprocessing is defined in the 'query_preprocessing.yaml' configuration
file. The file must contain a list of steps. Each step has a mandatory
parameter step which defines the type of preprocessor. Additional step
configuration may then be set with additional parameters.

The steps are executed in the order that they are defined in the configuration
file. Order matters here: each preprocessor works with the output of the previous
step.

Pre-defined preprocessors Copy Chapter

The following is a list of preprocessors that are shipped with Nominatim.
To learn how to define custom preprocessors, see the section on
query processing modules.

split-japanese-phrases Copy Section

::: nominatim_api.query_preprocessing.split_japanese_phrases
options:
members: False
heading_level: 6
docstring_section_style: spacy

regex-replace Copy Section

::: nominatim_api.query_preprocessing.regex_replace
options:
members: False
heading_level: 6
docstring_section_style: spacy

Customize Ranking (`docs/customize/Ranking.md`) Copy Section

Place Ranking in Nominatim

Nominatim uses two metrics to rank a place: search rank and address rank.
This chapter explains what place ranking means and how it can be customized.

Search rank Copy Chapter

The search rank describes the extent and importance of a place. It is used
when ranking search results. Simply put, if there are two results for a
search query which are otherwise equal, then the result with the lower
search rank will be appear higher in the result list.

Search ranks are not so important these days because many well-known
places use the Wikipedia importance ranking instead.

The following table gives an overview of the kind of features that Nominatim
expects for each rank:

The extent column describes how far a feature is assumed to reach when it
is mapped only as a point. Larger features like countries and states are usually
available with their exact area in the OpenStreetMap data. That is why no extent
is given.

Address rank Copy Chapter

The address rank describes where a place shows up in an address hierarchy.
Usually only administrative boundaries and place nodes and areas are
eligible to be part of an address. Places that should not appear in the
address must have an address rank of 0.

The following table gives an overview how ranks are mapped to address parts:

The country rank 4 usually doesn't show up in the address parts of an object.
The country is determined indirectly from the country code.

Ranks 5-24 can be assigned more or less freely. They make up the major part
of the address.

Rank 25 is also an addressing rank but it is special because while it can be
the parent to a POI with an addr:place of the same name, it cannot be a parent
to streets. Use it for place features that are technically on the same level
as a street (e.g. squares, city blocks) or for places that should not normally
appear in an address unless explicitly tagged so (e.g place=locality which
should be uninhabited and as such not addressable).

The street ranks 26 and 27 are handled slightly differently. Only one object
from these ranks shows up in an address.

For POI level objects like shops, buildings or house numbers always use rank 30.
Ranks 28 is reserved for house number interpolations. 29 is for internal use
only.

Rank configuration Copy Chapter

Search and address ranks are assigned to a place when it is first imported
into the database. There are a few hard-coded rules for the assignment:

• postcodes follow special rules according to their length
• boundaries that are not areas and railway=rail are dropped completely
• the following are always search rank 30 and address rank 0:
  • highway nodes
  • landuse that is not an area

Other than that, the ranks can be freely assigned via the JSON file according
to their type and the country they are in. The name of the config file to be
used can be changed with the setting NOMINATIM_ADDRESS_LEVEL_CONFIG.

The address level configuration must consist of an array of configuration
entries, each containing a tag definition and an optional country array:

[ {
    "tags" : {
      "place" : {
        "county" : 12,
        "city" : 16,
      },
      "landuse" : {
        "residential" : 22,
        "" : 30
      }
    }
  },
  {
    "countries" : [ "ca", "us" ],
    "tags" : {
      "boundary" : {
        "administrative8" : 18,
        "administrative9" : 20
      },
      "landuse" : {
        "residential" : [22, 0]
      }
    }
  }
]

The countries field contains a list of countries (as ISO 3166-1 alpha 2 code)
for which the definition applies. When the field is omitted, then the
definition is used as a fallback, when nothing more specific for a given
country exists.

tags contains the ranks for key/value pairs. The ranks can be either a
single number, in which case they are the search and address rank, or an array
of search and address rank (in that order). The value may be left empty.
Then the rank is used when no more specific value is found for the given
key.

Countries and key/value combination may appear in multiple definitions. Just
make sure that each combination of country/key/value appears only once per
file. Otherwise the import will fail with a UNIQUE INDEX constraint violation
on import.

Customize Result Formatting (`docs/customize/Result-Formatting.md`) Copy Section

Changing the Appearance of Results in the Server API

The Nominatim Server API offers a number of formatting options that
present search results in different output formats.
These results only contain a subset of all the information that Nominatim
has about the result. This page explains how to adapt the result output
or add additional result formatting.

Defining custom result formatting Copy Chapter

To change the result output, you need to place a file api/v1/format.py
into your project directory. This file needs to define a single variable
dispatch containing a FormatDispatcher. This class
serves to collect the functions for formatting the different result types
and offers helper functions to apply the formatters.

There are two ways to define the dispatch variable. If you want to reuse
the default output formatting and just make some changes or add an additional
format type, then import the dispatch object from the default API:

from nominatim_api.v1.format import dispatch as dispatch

If you prefer to define a completely new result output, then you can
create an empty dispatcher object:

from nominatim_api import FormatDispatcher

dispatch = FormatDispatcher()

The formatting function Copy Chapter

The dispatcher organises the formatting functions by format and result type.
The format corresponds to the format parameter of the API. It can contain
one of the predefined format names or you can invent your own new format.

API calls return data classes or an array of a data class which represent
the result. You need to make sure there are formatters defined for the
following result types:

• StatusResult (single object, returned by /status)
• DetailedResult (single object, returned by /details)
• SearchResults (list of objects, returned by /search)
• ReverseResults (list of objects, returned by /reverse and /lookup)
• RawDataList (simple object, returned by /deletable and /polygons)

A formatter function has the following signature:

def format_func(result: ResultType, options: Mapping[str, Any]) -> str

The options dictionary contains additional information about the original
query. See the reference below
about the possible options.

To set the result formatter for a certain result type and format, you need
to write the format function and decorate it with the
format_func
decorator.

For example, let us extend the result for the status call in text format
and add the server URL. Such a formatter would look like this:

from nominatim_api import StatusResult

@dispatch.format_func(StatusResult, 'text')
def _format_status_text(result, _):
    header = 'Status for server nominatim.openstreetmap.org'
    if result.status:
        return f"{header}\n\nERROR: {result.message}"

    return f"{header}\n\nOK"

If your dispatcher is derived from the default one, then this definition
will overwrite the original formatter function. This way it is possible
to customize the output of selected results.

Adding new formats Copy Chapter

You may also define a completely different output format. This is as simple
as adding formatting functions for all result types using the custom
format name:

from nominatim_api import StatusResult

@dispatch.format_func(StatusResult, 'chatty')
def _format_status_text(result, _):
    if result.status:
        return f"The server is currently not running. {result.message}"

    return "Good news! The server is running just fine."

That's all. Nominatim will automatically pick up the new format name and
will allow the user to use it. There is no need to implement formatter
functions for all the result types, when you invent a new one. The
available formats will be determined for each API endpoint separately.
To find out which formats are available, you can use the --list-formats
option of the CLI tool:

me@machine:planet-project$ nominatim status --list-formats
2024-08-16 19:54:00: Using project directory: /home/nominatim/planet-project
text
json
chatty
debug
me@machine:planet-project$

The debug format listed in the last line will always appear. It is a
special format that enables debug output via the command line (the same
as the debug=1 parameter enables for the server API). To not clash
with this built-in function, you shouldn't name your own format 'debug'.

Note that the debug format of the CLI is always available, while the
debug=1 parameter of the server API needs to be enabled explicitly with
NOMINATIM_SERVE_DEBUG_OUTPUT.

Content type of new formats Copy Section

All responses will be returned with the content type application/json by
default. If your format produces a different content type, you need
to configure the content type with the set_content_type() function.

For example, the 'chatty' format above returns just simple text. So the
content type should be set up as:

from nominatim_api.server.content_types import CONTENT_TEXT

dispatch.set_content_type('chatty', CONTENT_TEXT)

The content_types module used above provides constants for the most
frequent content types. You set the content type to an arbitrary string,
if the content type you need is not available.

Formatting error messages Copy Chapter

Any exception thrown during processing of a request is given to
a special error formatting function. It takes the requested content type,
the status code and the error message. It should return the error message
in a form appropriate for the given content type.

You can overwrite the default formatting function with the decorator
error_format_func:

import json
from xml.sax.saxutils import escape

import nominatim_api.server.content_types as ct

@dispatch.error_format_func
def _format_error(content_type: str, msg: str, status: int) -> str:
    if content_type == ct.CONTENT_XML:
        return f"""<?xml version="1.0" encoding="UTF-8" ?>
                     <message>{escape(msg)}</message>
                """
    if content_type == ct.CONTENT_JSON:
        return json.dumps(msg)

    return f"ERROR: {msg}"

Debugging custom formatters Copy Chapter

The easiest way to try out your custom formatter is by using the Nominatim
CLI commands. Custom formats can be chosen with the --format parameter:

me@machine:planet-project$ nominatim status --format chatty
2024-08-16 19:54:00: Using project directory: /home/nominatim/planet-project
Good news! The server is running just fine.
me@machine:planet-project$

They will also emit full error messages when there is a problem with the
code you need to debug.

!!! danger
In some cases, when you make an error with your import statement, the
CLI will not give you an error but instead tell you, that the API
commands are no longer available:

me@machine: nominatim status
    usage: nominatim [-h] [--version] {import,freeze,replication,special-phrases,add-data,index,refresh,admin} ...
    nominatim: error: argument subcommand: invalid choice: 'status'

This happens because the CLI tool is meant to still work when the
nominatim-api package is not installed. Import errors involving
`nominatim_api` are interpreted as "package not installed".

Use the help command to find out which is the offending import that
could not be found:

    me@machine: nominatim -h
    ... [other help text] ...
    Nominatim API package not found (was looking for module: nominatim_api.xxx).

Reference Copy Chapter

FormatDispatcher Copy Section

::: nominatim_api.FormatDispatcher
options:
heading_level: 6
group_by_category: False

JsonWriter Copy Section

::: nominatim_api.utils.json_writer.JsonWriter
options:
heading_level: 6
group_by_category: False

Options for different result types Copy Section

This section lists the options that may be handed in with the different result
types in the v1 version of the Nominatim API.

StatusResult

None.

DetailedResult

SearchResults

ReverseResults

RawDataList

None.

Customize SQLite (`docs/customize/SQLite.md`) Copy Section

A Nominatim database can be converted into an SQLite database and used as
a read-only source for geocoding queries. This sections describes how to
create and use an SQLite database.

!!! danger
This feature is in an experimental state at the moment. Use at your own
risk.

Installing prerequisites Copy Chapter

To use a SQLite database, you need to install:

• SQLite (>= 3.30)
• Spatialite (> 5.0.0)
• aiosqlite

On Ubuntu/Debian, you can run:

sudo apt install sqlite3 libsqlite3-mod-spatialite libspatialite7

Install the aiosqlite Python package in your virtual environment:

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

Creating a new SQLite database Copy Chapter

Nominatim cannot import directly into SQLite database. Instead you have to
first create a geocoding database in PostgreSQL by running a
regular Nominatim import.

Once this is done, the database can be converted to SQLite with

nominatim convert -o mydb.sqlite

This will create a database where all geocoding functions are available.
Depending on what functions you need, the database can be made smaller:

• --without-reverse omits indexes only needed for reverse geocoding
• --without-search omit tables and indexes used for forward search
• --without-details leaves out extra information only available in the
  details API

Using an SQLite database Copy Chapter

Once you have created the database, you can use it by simply pointing the
database DSN to the SQLite file:

NOMINATIM_DATABASE_DSN=sqlite:dbname=mydb.sqlite

Please note that SQLite support is only available for the Python frontend. To
use the test server with an SQLite database, you therefore need to switch
the frontend engine:

nominatim serve --engine falcon

You need to install falcon or starlette for this, depending on which engine
you choose.

The CLI query commands and the library interface already use the new Python
frontend and therefore work right out of the box.

Customize Sanitizers (`docs/customize/Sanitizers.md`) Copy Section

Sanitizers

Sanitizing is the process of cleaning up and otherwise preprocessing names
before adding them to the search index during the import process. This allows
to clean up tagging, normalise different spellings and mark names with extra
attributes for further processing.

!!! hint
Sanitizers only have an effect on how the search index is built. They
do not change the information about each place that is saved in the
database. In particular, they have no influence on how the results are
displayed. The returned results always show the original information as
stored in the OpenStreetMap database.

Configuration Copy Chapter

The sanitizing process is defined in the 'sanitizers.yaml' configuration
file. The file must contain a list of steps. Each step has a mandatory
parameter step which defines the type of sanitizer. Additional step
configuration may then be set with additional parameters.

The steps are executed in the order that they are defined in the configuration
file. Order matters here: each sanitizer works with the output of the previous
step.

Pre-defined sanitizers Copy Chapter

The following is a list of sanitizers that are shipped with Nominatim.
To learn about how to add your own custom sanitizer, see the section on
custom sanitizer modules.

affix-expansion Copy Section

::: nominatim_db.tokenizer.sanitizers.affix_expansion
options:
members: False
heading_level: 6
docstring_section_style: spacy

clean-housenumbers Copy Section

::: nominatim_db.tokenizer.sanitizers.clean_housenumbers
options:
members: False
heading_level: 6
docstring_section_style: spacy

clean-multilingual-names Copy Section

::: nominatim_db.tokenizer.sanitizers.clean_multilingual_names
options:
members: False
heading_level: 6
docstring_section_style: spacy

clean-postcodes Copy Section

::: nominatim_db.tokenizer.sanitizers.clean_postcodes
options:
members: False
heading_level: 6
docstring_section_style: spacy

clean-tiger-tags Copy Section

::: nominatim_db.tokenizer.sanitizers.clean_tiger_tags
options:
members: False
heading_level: 6
docstring_section_style: spacy

delete-names Copy Section

::: nominatim_db.tokenizer.sanitizers.delete_names
options:
members: False
heading_level: 6
docstring_section_style: spacy

derive-names Copy Section

::: nominatim_db.tokenizer.sanitizers.derive_names
options:
members: False
heading_level: 6
docstring_section_style: spacy

split-name-list Copy Section

::: nominatim_db.tokenizer.sanitizers.split_name_list
options:
members: False
heading_level: 6
docstring_section_style: spacy

strip-brace-terms Copy Section

::: nominatim_db.tokenizer.sanitizers.strip_brace_terms
options:
members: False
heading_level: 6
docstring_section_style: spacy

tag-analyzer-by-language Copy Section

::: nominatim_db.tokenizer.sanitizers.tag_analyzer_by_language
options:
members: False
heading_level: 6
docstring_section_style: spacy

tag-japanese Copy Section

::: nominatim_db.tokenizer.sanitizers.tag_japanese
options:
members: False
heading_level: 6
docstring_section_style: spacy

Customize Settings (`docs/customize/Settings.md`) Copy Section

This section provides a reference of all configuration parameters that can
be used with Nominatim.

Configuring Nominatim

Nominatim uses dotenv to manage
its configuration settings. There are two means to set configuration
variables: through an .env configuration file or through an environment
variable.

The .env configuration file needs to be placed into the
project directory. It
must contain configuration parameters in =<value> format.
Please refer to the dotenv documentation for details.

The configuration options may also be set in the form of shell environment
variables. This is particularly useful, when you want to temporarily change
a configuration option. For example, to force the replication serve to
download the next change, you can temporarily disable the update interval:

NOMINATIM_REPLICATION_UPDATE_INTERVAL=0 nominatim replication --once

If a configuration option is defined through .env file and environment
variable, then the latter takes precedence.

Configuration Parameter Reference Copy Chapter

Import and Database Settings Copy Section

NOMINATIM_DATABASE_DSN

Sets the connection parameters for the Nominatim database. At a minimum
the name of the database (dbname) is required. You can set any additional
parameter that is understood by libpq. See the Postgres documentation for a full list.

!!! note
It is usually recommended not to set the password directly in this
configuration parameter. Use a
password file
instead.

NOMINATIM_DATABASE_WEBUSER

Defines the name of the database user that will run search queries. Usually
this is the user under which the webserver is executed. The Postgres user
needs to be set up before starting the import.

Nominatim grants minimal rights to this user to all tables that are needed
for running geocoding queries.

NOMINATIM_TOKENIZER

Sets the tokenizer type to use for the import. For more information on
available tokenizers and how they are configured, see
Tokenizers.

NOMINATIM_TOKENIZER_CONFIG

Points to the file with additional configuration for the tokenizer.
See the Tokenizer descriptions for details
on the file format.

If a relative path is given, then the file is searched first relative to the
project directory and then in the global settings directory.

NOMINATIM_LIMIT_REINDEXING

Nominatim computes the address of each place at indexing time. This has the
advantage to make search faster but also means that more objects needs to
be invalidated when the data changes. For example, changing the name of
the state of Florida would require recomputing every single address point
in the state to make the new name searchable in conjunction with addresses.

Setting this option to 'yes' means that Nominatim skips reindexing of contained
objects when the area becomes too large.

NOMINATIM_LANGUAGES

Normally Nominatim will include all language variants of name:XX
in the search index. Set this to a comma separated list of language
codes, to restrict import to a subset of languages.

Currently only affects the initial import of country names and special phrases.

NOMINATIM_USE_US_TIGER_DATA

When this setting is enabled, search and reverse queries also take data
from Tiger house number data into account.

NOMINATIM_OSM2PGSQL_BINARY

Nominatim uses osm2pgsql to load the OSM data
initially into the database. Nominatim comes bundled with a version of
osm2pgsql that is guaranteed to be compatible. Use this setting to use
a different binary instead. You should do this only when you know exactly
what you are doing. If the osm2pgsql version is not compatible, then the
result is undefined.

NOMINATIM_WIKIPEDIA_DATA_PATH

Set a custom location for the
wikipedia ranking file. When
unset, Nominatim expects the data to be saved in the project directory.

NOMINATIM_ADDRESS_LEVEL_CONFIG

The address level configuration defines the rank assignments for places. See
Place Ranking for a detailed explanation what rank assignments
are and what the configuration file must look like.

When a relative path is given, then the file is searched first relative to the
project directory and then in the global settings directory.

NOMINATIM_IMPORT_STYLE

The style configuration describes which OSM objects and tags are taken
into consideration for the search database. Nominatim comes with a set
of pre-configured styles, that may be configured here.

You can also write your own custom style and point the setting to the file
with the style. When a relative path is given, then the style file is searched
first relative to the project directory and then in the global settings
directory.

See Import Styles
for more information on the available internal styles and the format of the
configuration file.

NOMINATIM_FLATNODE_FILE

The osm2pgsql flatnode file is file that efficiently stores geographic
location for OSM nodes. For larger imports it can significantly speed up
the import. When this option is unset, then osm2pgsql uses a PsotgreSQL table
to store the locations.

When a relative path is given, then the flatnode file is created/searched
relative to the project directory.

!!! warning

The flatnode file is not only used during the initial import but also
when adding new data with `nominatim add-data` or `nominatim replication`.
Make sure you keep the flatnode file around and this setting unmodified,
if you plan to add more data or run regular updates.

NOMINATIM_TABLESPACE_*

Nominatim allows to distribute the search database over up to 10 different
PostgreSQL tablespaces.
If you use this option, make sure that the tablespaces exist before starting
the import.

The available tablespace groups are:

NOMINATIM_TABLESPACE_SEARCH_DATA
: Data used by the geocoding frontend.

NOMINATIM_TABLESPACE_SEARCH_INDEX
: Indexes used by the geocoding frontend.

NOMINATIM_TABLESPACE_OSM_DATA
: Raw OSM data cache used for import and updates.

NOMINATIM_TABLESPACE_OSM_INDEX
: Indexes on the raw OSM data cache.

NOMINATIM_TABLESPACE_PLACE_DATA
: Data table with the pre-filtered but still unprocessed OSM data.
Used only during imports and updates.

NOMINATIM_TABLESPACE_PLACE_INDEX
: Indexes on raw data table. Used only during imports and updates.

NOMINATIM_TABLESPACE_ADDRESS_DATA
: Data tables used for computing search terms and addresses of places
during import and updates.

NOMINATIM_TABLESPACE_ADDRESS_INDEX
: Indexes on the data tables for search term and address computation.
Used only for import and updates.

NOMINATIM_TABLESPACE_AUX_DATA
: Auxiliary data tables for non-OSM data, e.g. for Tiger house number data.

NOMINATIM_TABLESPACE_AUX_INDEX
: Indexes on auxiliary data tables.

Replication Update Settings Copy Section

NOMINATIM_REPLICATION_URL

Replication services deliver updates to OSM data. Use this setting to choose
which replication service to use. See Updates for more
information on how to set up regular updates.

NOMINATIM_REPLICATION_MAX_DIFF

At each update cycle Nominatim downloads diffs until either no more diffs
are available on the server (i.e. the database is up-to-date) or the limit
given in this setting is exceeded. Nominatim guarantees to downloads at least
one diff, if one is available, no matter how small the setting.

The default for this setting is fairly conservative because Nominatim keeps
all data downloaded in one cycle in RAM. Using large values in a production
server may interfere badly with the search frontend because it evicts data
from RAM that is needed for speedy answers to incoming requests. It is usually
a better idea to keep this setting lower and run multiple update cycles
to catch up with updates.

When catching up in non-production mode, for example after the initial import,
the setting can easily be changed temporarily on the command line:

NOMINATIM_REPLICATION_MAX_DIFF=3000 nominatim replication

NOMINATIM_REPLICATION_UPDATE_INTERVAL

This setting determines when Nominatim will attempt to download again a new
update. The time is computed from the publication date of the last diff
downloaded. Setting this to a slightly higher value than the actual
publication interval avoids unnecessary rechecks.

NOMINATIM_REPLICATION_RECHECK_INTERVAL

When replication updates are run in continuous mode (using nominatim replication),
this setting determines how long Nominatim waits until it looks for updates
again when updates were not available on the server.

Note that this is different from
NOMINATIM_REPLICATION_UPDATE_INTERVAL.
Nominatim will never attempt to query for new updates for UPDATE_INTERVAL
seconds after the current database date. Only after the update interval has
passed it asks for new data. If then no new data is found, it waits for
RECHECK_INTERVAL seconds before it attempts again.

API Settings Copy Section

NOMINATIM_CORS_NOACCESSCONTROL

When this setting is enabled, API HTTP responses include the HTTP
CORS headers
access-control-allow-origin: * and access-control-allow-methods: OPTIONS,GET.

NOMINATIM_MAPICON_URL

When a mapicon URL is configured, then Nominatim includes an additional icon
field in the responses, pointing to an appropriate icon for the place type.

Map icons used to be included in Nominatim itself but now have moved to the
nominatim-ui project. If you
want the URL to be included in API responses, make the /mapicon
directory of the project available under a public URL and point this setting
to the directory.

NOMINATIM_DEFAULT_LANGUAGE

Nominatim localizes the place names in responses when the corresponding
translation is available. Users can request a custom language setting through
the HTTP accept-languages header or through the explicit parameter
accept-languages. If neither is
given, it falls back to this setting. If the setting is also empty, then
the local languages (in OSM: the name tag without any language suffix) is
used.

NOMINATIM_LOOKUP_MAX_COUNT

The /lookup point accepts list of ids to look up address details for. This
setting restricts the number of places a user may look up with a single
request.

NOMINATIM_POLYGON_OUTPUT_MAX_TYPES

Nominatim supports returning full geometries of places. The geometries may
be requested in different formats with one of the
polygon_* parameters. Use this
setting to restrict the number of geometry types that may be requested
with a single query.

Setting this parameter to 0 disables polygon output completely.

NOMINATIM_SEARCH_WITHIN_COUNTRIES

Enable to search elements just within countries.

When enabled, if, despite not finding a point within the static grid of countries, it
finds a geometry of a region, do not return the geometry.
Return "Unable to geocode" instead.

NOMINATIM_SERVE_LEGACY_URLS

When enabled, then endpoints are reachable as /<name> as well as /<name>.php.
This can be useful when you want to be backwards-compatible with previous
versions of Nominatim.

NOMINATIM_SERVE_DEBUG_OUTPUT

When enabled, requests to /search, /reverse, /lookup and /details with
the parameter debug=1 return an HTML page detailing how the query was
parsed, understood and executed.

The debug format of the command-line tool (nominatim search --format debug),
which has a similar output (text instead of HTML), is always available.

NOMINATIM_API_POOL_SIZE

Sets the maximum number of database connections available for a single instance
of Nominatim. When configuring the maximum number of connections that your
PostgreSQL database can handle, you need at least
NOMINATIM_API_POOL_SIZE * <number of configured workers> connections.
For configuring the number of workers, refer to the section about
Deploying the Python frontend.

NOMINATIM_QUERY_TIMEOUT

When this timeout is set, then all SQL queries that run longer than the
specified numbers of seconds will be cancelled and the user receives a
timeout exceptions. Users of the API see a 503 HTTP error.

The timeout does ont apply when using the
low-level DB access
of the library. A timeout can be manually set, if required.

NOMINATIM_REQUEST_TIMEOUT

When this timeout is set, a search query will finish sending queries
to the database after the timeout has passed and immediately return the
results gathered so far.

Note that under high load you may observe that users receive different results
than usual without seeing an error. This may cause some confusion.

NOMINATIM_OUTPUT_NAMES

Specifies the order in which different name tags are used.
The values in this list determine the preferred order of name variants,
including language-specific names (in OSM: the name tag with and without any language suffix).

Comma-separated list, where :XX stands for language suffix
(e.g. name:en) and no :XX stands for general tags (e.g. name).

See also NOMINATIM_DEFAULT_LANGUAGE.

!!! note
If NOMINATIM_OUTPUT_NAMES = name:XX,name,short_name:XX,short_name the search follows

```
    'name', 'short_name'
    ```

if we have no preferred language order for showing search results.

For languages ['en', 'es'] the search follows

    ```
    'name:en', 'name:es',
    'name',
    'short_name:en', 'short_name:es',
    'short_name'
    ```

For those familiar with the internal implementation, the `_place_*` expansion is added, but to simplify, it is not included in this example.

Logging Settings Copy Section

NOMINATIM_LOG_FILE

Enable logging of requests into a file with this setting by setting the log
file where to log to. A relative file name is assumed to be relative to
the project directory. The format of the log output can be set
with NOMINATIM_LOG_FORMAT.

NOMINATIM_LOG_FORMAT

Describes the content of a log line for a single request. The format
must be readable by Python's format function. Nominatim provides a number
of metrics than can be logged. The default set of metrics is the following:

/// html | div.simple-table