### New structure for Python packages
-The nominatim Python package has been split into nominatim-db and nominatim-api.
+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
and how to run tests.
!!! Important
- This guide assumes that you develop under the latest version of Debain/Ubuntu.
+ This guide assumes you develop under the latest version of Debian/Ubuntu.
You can of course also use your favourite distribution. You just might have
to adapt the commands below slightly, in particular the commands for
installing additional software.
For testing the Python search frontend, you need to install extra dependencies
depending on your choice of webserver framework:
-* [httpx](https://www.python-httpx.org/) (starlette only)
-* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (starlette only)
+* [httpx](https://www.python-httpx.org/) (Starlette only)
+* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (Starlette only)
The documentation is built with mkdocs:
but executes against the code in the source tree. For example:
```
-me@machine:~$ cd Nomiantim
-me@machine:~Nomiantim$ ./nominatim-cli.py --version
+me@machine:~$ cd Nominatim
+me@machine:~Nominatim$ ./nominatim-cli.py --version
Nominatim version 4.4.99-1
```
-Make sure you have activated the virtual environment that holds all
+Make sure you have activated the virtual environment holding all
necessary dependencies.
## Executing Tests
make tests
```
-There are also goals for executing parts of the test suite: mypy, lint, pytest, bdd.
+There are also make targets for executing only parts of the test suite.
+For example to run linting only use:
+
+```sh
+make lint
+```
+
+The possible testing targets are: mypy, lint, pytest, bdd.
For more information about the structure of the tests and how to change and
extend the test suite, see the [Testing chapter](Testing.md).
Follow the [installation](../admin/Installation.md) and
[import](../admin/Import.md) instructions to set up your database.
-The Nominatim frontend library is contained in the 'nominatim-api' package.
+The Nominatim frontend library is contained in the Python package `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.
+Usually you would want to run this in a virtual environment.
### A simple search example
by name and address (geocoding) and to generate synthetic addresses of
OSM points (reverse geocoding).
-This module implements the library for searching in a Nominatim database
-imported with the 'nominatim-db' package.
+This module implements the library for searching a Nominatim database
+imported with the [`nominatim-db`](https://pypi.org/project/nominatim-db/) package.
## Installation
## Running a Nominatim server
-You need falcon or starlette to run Nominatim as a service, as well as
+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
## Documentation
The full documentation for the Nominatim library can be found at:
-https://nominatim.org/release-docs/develop/library/Getting-Started/
+https://nominatim.org/release-docs/latest/library/Getting-Started/
The v1 API of the server is documented at:
-https://nominatim.org/release-docs/develop/api/Overview/
+https://nominatim.org/release-docs/latest/api/Overview/
## License
[project.urls]
Homepage = "https://nominatim.org"
+Documentation = "https://nominatim.org/release-docs/latest/"
Issues = "https://github.com/osm-search/Nominatim/issues"
+Repository = "https://github.com/osm-search/Nominatim"
[build-system]
requires = ["hatchling"]
### Prerequisites
Nominatim requires [osm2pgsql](https://osm2pgsql.org/) (>=1.8) for reading
-OSM data and [PostgreSQL](https://www.postgresql.org/) to store the data.
+OSM data and [PostgreSQL](https://www.postgresql.org/) (>=9.6) to store the data.
-On Ubuntu (>=23.04) and Debian (using backports), you can install them with:
+On Ubuntu (>=23.04) and Debian (when using backports), you can install them with:
sudo apt-get install osm2pgsql postgresql-postgis
First create a project directory for your new Nominatim database, which
is the space for additional configuration and customization:
- mkdir planet-project
+ 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](https://download.geofabrik.de/) 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.
+You will need to install the [`nominatim-api`](https://pypi.org/project/nominatim-api/)
+package to query the database.
## 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/ .
+A HTML version of the documentation can be found at
+https://nominatim.org/release-docs/latest/ .
## License
[project.urls]
Homepage = "https://nominatim.org"
-Issues = "https://github.com/osm-search/Nominatim/issues"
Documentation = "https://nominatim.org/release-docs/latest/"
+Issues = "https://github.com/osm-search/Nominatim/issues"
+Repository = "https://github.com/osm-search/Nominatim"
[build-system]
requires = ["hatchling"]
# ---------------------
#
# Tune the postgresql configuration, which is located in
-# `/etc/postgresql/14/main/postgresql.conf`. See section *Tuning the PostgreSQL database*
+# `/etc/postgresql/16/main/postgresql.conf`. See section *Tuning the PostgreSQL database*
# in [the installation page](../admin/Installation.md#tuning-the-postgresql-database)
# for the parameters to change.
#
# Nominatim is now ready to use. The nominatim binary is available at
# `$USERHOME/venv/bin/nominatim`. If you want to have 'nominatim' in your
# path, simply activate the virtual environment:
-
-
-
+#
+#DOCS:```sh
+# . $USERHOME/nominatim-venv/bin/activate
+#DOCS:```
+#
# You can continue with
# [importing a database from OSM data](../admin/Import.md). If you want to set up
# the API frontend first, continue reading.
# ==============================
#
# The Python frontend is contained in the nominatim-api package. To run
-# the API as a webservice, you also need falcon with uvicorn/gunicorn to
-# serve the API.
+# the API as a webservice, you also need falcon with uvicorn to serve the API.
+# It is generally recommended to run falcon/uvicorn on top of gunicorn.
#
# To install all packages, run:
projects / nominatim.git / commitdiff