diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index edfc8829..637ecfe9 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -11,6 +11,7 @@ set (DOC_SOURCES develop api customize + library index.md extra.css styles.css @@ -25,10 +26,10 @@ endforeach() ADD_CUSTOM_TARGET(doc COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-20.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-20.md COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-22.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-22.md - COMMAND PYTHONPATH=${PROJECT_SOURCE_DIR} mkdocs build -d ${CMAKE_CURRENT_BINARY_DIR}/../site-html -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml + COMMAND mkdocs build -d ${CMAKE_CURRENT_BINARY_DIR}/../site-html -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml ) ADD_CUSTOM_TARGET(serve-doc - COMMAND PYTHONPATH=${PROJECT_SOURCE_DIR} mkdocs serve - WORKING_DIRECTORY ${PROJECT_BINARY_DIR} + COMMAND mkdocs serve -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml + WORKING_DIRECTORY ${PROJECT_SOURCE_DIR} ) diff --git a/docs/admin/Deployment.md b/docs/admin/Deployment-PHP.md similarity index 95% rename from docs/admin/Deployment.md rename to docs/admin/Deployment-PHP.md index 8b635546..92c1a4ec 100644 --- a/docs/admin/Deployment.md +++ b/docs/admin/Deployment-PHP.md @@ -1,4 +1,4 @@ -# Deploying Nominatim +# Deploying Nominatim using the PHP frontend The Nominatim API is implemented as a PHP application. The `website/` directory in the project directory contains the configured website. You can serve this @@ -13,8 +13,8 @@ to run a web service. Please refer to the documentation of for background information on configuring the services. !!! Note - Throughout this page, we assume that your Nominatim project directory is - located in `/srv/nominatim-project` and that you have installed Nominatim + Throughout this page, we assume your Nominatim project directory is + located in `/srv/nominatim-project` and you have installed Nominatim using the default installation prefix `/usr/local`. If you have put it somewhere else, you need to adjust the commands and configuration accordingly. diff --git a/docs/admin/Deployment-Python.md b/docs/admin/Deployment-Python.md new file mode 100644 index 00000000..c3cca59b --- /dev/null +++ b/docs/admin/Deployment-Python.md @@ -0,0 +1,122 @@ +# Deploying the Nominatim Python frontend + +The Nominatim can be run as a Python-based +[ASGI web application](https://asgi.readthedocs.io/en/latest/). You have the +choice between [Falcon](https://falcon.readthedocs.io/en/stable/) +and [Starlette](https://www.starlette.io/) 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](https://nginx.org/en/docs/) for background information on how +to configure it. + +!!! Note + Throughout this page, we assume your Nominatim project directory is + located in `/srv/nominatim-project` and you have installed Nominatim + using the default installation prefix `/usr/local`. If you have put it + somewhere else, you need to adjust the commands and configuration + accordingly. + + We further assume that your web server runs as user `www-data`. Older + versions of CentOS may still use the user name `apache`. You also need + to adapt the instructions in this case. + +### Installing the required packages + +The recommended way to deploy a Python ASGI application is to run +the ASGI runner (uvicorn)[https://uvicorn.org/] +together with (gunicorn)[https://gunicorn.org/] HTTP server. We use +Falcon here as the web framework. + +Create a virtual environment for the Python packages and install the necessary +dependencies: + +``` sh +sudo apt install virtualenv +virtualenv /srv/nominatim-venv +/srv/nominatim-venv/bin/pip install SQLAlchemy PyICU psycopg[binary]\ + psycopg2-binary python-dotenv PyYAML falcon uvicorn gunicorn +``` + +### Setting up Nominatim as a systemd job + +Next you need to set up the service that runs the Nominatim frontend. This is +easiest done with a systemd job. + +Create the following file `/etc/systemd/system/nominatim.service`: + +``` systemd +[Unit] +Description=Nominatim running as a gunicorn application +After=network.target +Requires=nominatim.socket + +[Service] +Type=simple +Environment="PYTHONPATH=/usr/local/lib/nominatim/lib-python/" +User=www-data +Group=www-data +WorkingDirectory=/srv/nominatim-project +ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi +ExecReload=/bin/kill -s HUP $MAINPID +StandardOutput=append:/var/log/gunicorn-nominatim.log +StandardError=inherit +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`](../customize/Settings.md#nominatim_api_pool_size) +connections to the database to serve requests in parallel. + +Make the new service known to systemd and start it: + +``` sh +sudo systemctl daemon-reload +sudo systemctl enable nominatim +sudo systemctl start nominatim +``` + +This sets the service up, so that Nominatim is automatically started +on reboot. + +### Configuring nginx + +To make the service available to the world, you need to proxy it through +nginx. Add the following definition to the default configuration: + +``` nginx +upstream nominatim_service { + server unix:/run/nominatim.sock fail_timeout=0; +} + +server { + listen 80; + listen [::]:80; + + root /var/www/html; + index /search; + + location / { + proxy_set_header Host $http_host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_redirect off; + proxy_pass http://nominatim_service; + } +} +``` + +Reload nginx with + +``` +sudo systemctl reload nginx +``` + +and you should be able to see the status of your server under +`http://localhost/status`. diff --git a/docs/admin/Import.md b/docs/admin/Import.md index d84a2376..0fd5ec29 100644 --- a/docs/admin/Import.md +++ b/docs/admin/Import.md @@ -254,26 +254,70 @@ successfully. nominatim admin --check-database ``` -Now you can try out your installation by running: +Now you can try out your installation by executing a simple query on the +command line: + +``` sh +nominatim search --query Berlin +``` + +or, when you have a reverse-only installation: + +``` sh +nominatim reverse --lat 51 --lon 45 +``` + +If you want to run Nominatim as a service, you need to make a choice between +running the traditional PHP frontend or the new experimental Python frontend. +Make sure you have installed the right packages as per +[Installation](Installation.md#software). + +#### Testing the PHP frontend + +You can run a small test server with the PHP frontend like this: ```sh nominatim serve ``` -This runs a small test server normally used for development. You can use it -to verify that your installation is working. Go to -`http://localhost:8088/status.php` and you should see the message `OK`. -You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin`. +Go to `http://localhost:8088/status.php` and you should see the message `OK`. +You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin` +or, for reverse-only installations a reverse query, +e.g. `http://localhost:8088/reverse.php?lat=27.1750090510034&lon=78.04209025`. -Note that search query is not supported for reverse-only imports. You can run a -reverse query, e.g. `http://localhost:8088/reverse.php?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 PHP frontend](Deployment-PHP.md). -To run Nominatim via webservers like Apache or nginx, please read the -[Deployment chapter](Deployment.md). +#### Testing the Python frontend -## Adding search through category phrases +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 -If you want to be able to search for places by their type through +``` sh +nominatim serve --engine falcon +``` + +or + +``` sh +nominatim serve --engine starlette +``` + +Go to `http://localhost:8088/status.php` and you should see the message `OK`. +You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin` +or, for reverse-only installations a reverse query, +e.g. `http://localhost:8088/reverse.php?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](Deployment-Python.md). + + +## Enabling search by category phrases + +To be able to search for places by their type using [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) you also need to import these key phrases like this: diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md index abcd89d8..3de913b4 100644 --- a/docs/admin/Installation.md +++ b/docs/admin/Installation.md @@ -54,6 +54,8 @@ For running Nominatim: * [PyICU](https://pypi.org/project/PyICU/) * [PyYaml](https://pyyaml.org/) (5.1+) * [datrie](https://github.com/pytries/datrie) + +When running the PHP frontend: * [PHP](https://php.net) (7.3+) * PHP-pgsql * PHP-intl (bundled with PHP) @@ -83,7 +85,7 @@ 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 days. On traditional spinning disks, 7-8 days are more realistic. +around 2 days. When using traditional SSDs, 4-5 days are more realistic. ## Tuning the PostgreSQL database @@ -115,15 +117,6 @@ you might consider setting: and even reduce `autovacuum_work_mem` further. This will reduce the amount of memory that autovacuum takes away from the import process. -For the initial import, you should also set: - - fsync = off - full_page_writes = off - -Don't forget to re-enable them after the initial import or you risk database -corruption. - - ## Downloading and building Nominatim ### Downloading the latest release diff --git a/docs/api/Details.md b/docs/api/Details.md index 08802f9a..c50378c5 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -2,13 +2,17 @@ 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](https://github.com/osm-search/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 page exists for debugging only. You may not use it in scripts - or to automatically query details about a result. + The details endpoint at https://nominatim.openstreetmap.org + may not used in scripts or bots at all. See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/). -## Parameters The details API supports the following two request formats: @@ -35,59 +39,90 @@ 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. +!!! 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. -Additional optional parameters are explained below. + +## Parameters + +This section lists additional optional parameters. ### Output format -* `json_callback=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | -Wrap JSON output in a callback function (JSONP) i.e. `()`. +When set, then JSON output will be wrapped in a callback function with +the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more +information. -* `pretty=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| pretty | 0 or 1 | 0 | -Add indentation to make it more human-readable. (Default: 0) +`[PHP-only]` Add indentation to the output to make it more human-readable. ### Output details -* `addressdetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| addressdetails | 0 or 1 | 0 | -Include a breakdown of the address into elements. (Default: 0) +When set to 1, include a breakdown of the address into elements. -* `keywords=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| keywords | 0 or 1 | 0 | -Include a list of name keywords and address keywords (word ids). (Default: 0) +When set to 1, include a list of name keywords and address keywords +in the result. -* `linkedplaces=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| linkedplaces | 0 or 1 | 1 | -Include a details of places that are linked with this one. Places get linked +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. -(Default: 1) -* `hierarchy=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| hierarchy | 0 or 1 | 0 | -Include details of places lower in the address hierarchy. (Default: 0) +Include details of places lower in the address hierarchy. -* `group_hierarchy=[0|1]` +`[Python-only]` will only return properly parented places. These are address +or POI-like places that reuse the address of their parent street or place. -For JSON output will group the places by type. (Default: 0) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| group_hierarchy | 0 or 1 | 0 | -* `polygon_geojson=[0|1]` +When set to 1, the output of the address hierarchy will be +grouped by type. -Include geometry of result. (Default: 0) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | + + +Include geometry of result. ### Language of results -* `accept-language=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| accept-language | browser language string | content of "Accept-Language" HTTP header | -Preferred language order for showing result, overrides the value -specified in the "Accept-Language" HTTP header. -Either use a standard RFC2616 accept-language string or a simple -comma-separated list of language codes. +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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). ## Examples diff --git a/docs/api/Lookup.md b/docs/api/Lookup.md index e91c1770..a2ba714e 100644 --- a/docs/api/Lookup.md +++ b/docs/api/Lookup.md @@ -3,7 +3,7 @@ The lookup API allows to query the address and other details of one or multiple OSM objects like node, way or relation. -## Parameters +## Endpoint The lookup API has the following format: @@ -15,75 +15,129 @@ The lookup API has the following format: prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids can be queried at the same time. -Additional optional parameters are explained below. +!!! 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 + +This section lists additional optional parameters. ### Output format -* `format=[xml|json|jsonv2|geojson|geocodejson]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| format | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `jsonv2` | -See [Place Output Formats](Output.md) for details on each format. (Default: xml) +See [Place Output Formats](Output.md) for details on each format. -* `json_callback=` -Wrap JSON output in a callback function (JSONP) i.e. `()`. +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | + +When given, then JSON output will be wrapped in a callback function with +the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more +information. + Only has an effect for JSON output formats. + ### Output details -* `addressdetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| addressdetails | 0 or 1 | 0 | -Include a breakdown of the address into elements. (Default: 0) +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. -* `extratags=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| extratags | 0 or 1 | 0 | -Include additional information in the result if available, -e.g. wikipedia link, opening hours. (Default: 0) +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. -* `namedetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| namedetails | 0 or 1 | 0 | -Include a list of alternative names in the results. These may include -language variants, references, operator and brand. (Default: 0) +When set to 1, include a full list of names for the result. These may include +language variants, older names, references and brand. ### Language of results -* `accept-language=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| accept-language | browser language string | content of "Accept-Language" HTTP header | + +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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). + +!!! 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 contratry always + send the currently chosen browser language. -Preferred language order for showing search results, overrides the value -specified in the "Accept-Language" HTTP header. -Either use a standard RFC2616 accept-language string or a simple -comma-separated list of language codes. ### Polygon output -* `polygon_geojson=1` -* `polygon_kml=1` -* `polygon_svg=1` -* `polygon_text=1` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | +| polygon_kml | 0 or 1 | 0 | +| polygon_svg | 0 or 1 | 0 | +| polygon_text | 0 or 1 | 0 | -Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these -options can be used at a time. (Default: 0) +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. -* `polygon_threshold=0.0` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_threshold | floating-point number | 0.0 | -Return a simplified version of the output geometry. The parameter is the +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 result. (Default: 0.0) +geometry. Topology is preserved in the geometry. + ### Other -* `email=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| email | valid email address | _unset_ | If you are making large numbers of request please include an appropriate email -address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. +address to identify your requests. See Nominatim's +[Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. -* `debug=[0|1]` + +| Parameter | Value | Default | +|-----------| ----- | ------- | +| debug | 0 or 1 | 0 | Output assorted developer debug information. Data on internals of Nominatim's -"Search Loop" logic, and SQL queries. The output is (rough) HTML format. -This overrides the specified machine readable format. (Default: 0) +"search loop" logic, and SQL queries. The output is HTML format. +This overrides the specified machine readable format. ## Examples diff --git a/docs/api/Overview.md b/docs/api/Overview.md index a718079d..383eef53 100644 --- a/docs/api/Overview.md +++ b/docs/api/Overview.md @@ -1,8 +1,16 @@ ### Nominatim API -Nominatim indexes named (or numbered) features within the OpenStreetMap (OSM) dataset and a subset of other unnamed features (pubs, hotels, churches, etc). +!!! Attention + The current version of Nominatim implements two different search frontends: + the old PHP frontend and the new Python frontend. They have a very similar + API but differ in some implementation details. These are marked in the + documentation as `[Python-only]` or `[PHP-only]`. -Its API has the following endpoints for querying the data: + `https://nominatim.openstreetmap.org` implements the **Python frontend**. + So users should refer to the **`[Python-only]`** comments. + +This section describes the API V1 of the Nominatim web service. The +service offers the following endpoints: * __[/search](Search.md)__ - search OSM objects by name or type * __[/reverse](Reverse.md)__ - search OSM object by their location @@ -12,3 +20,6 @@ Its API has the following endpoints for querying the data: back in Nominatim in case the deletion was accidental * __/polygons__ - list of broken polygons detected by Nominatim * __[/details](Details.md)__ - show internal details for an object (for debugging only) + + + diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md index 56281d06..548b245c 100644 --- a/docs/api/Reverse.md +++ b/docs/api/Reverse.md @@ -1,6 +1,7 @@ # Reverse Geocoding -Reverse geocoding generates an address from a latitude and longitude. +Reverse geocoding generates an address from a coordinate given as +latitude and longitude. ## How it works @@ -18,8 +19,7 @@ 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. - -## Parameters +## Endpoint The main format of the reverse API is @@ -31,57 +31,101 @@ 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. -Additional parameters are accepted as listed below. -!!! warning "Deprecation warning" +!!! danger "Deprecation warning" The reverse API used to allow address lookup for a single OSM object by - its OSM id. This use is now deprecated. Use the [Address Lookup API](Lookup.md) - instead. + its OSM id for `[PHP-only]`. The use is considered deprecated. + Use the [Address Lookup API](Lookup.md) 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 + +This section lists additional parameters to further influence the output. ### Output format -* `format=[xml|json|jsonv2|geojson|geocodejson]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| format | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `xml` | -See [Place Output Formats](Output.md) for details on each format. (Default: xml) +See [Place Output Formats](Output.md) for details on each format. -* `json_callback=` -Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `()`. +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | + +When given, then JSON output will be wrapped in a callback function with +the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more +information. + Only has an effect for JSON output formats. + ### Output details -* `addressdetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| addressdetails | 0 or 1 | 1 | -Include a breakdown of the address into elements. (Default: 1) +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. -* `extratags=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| extratags | 0 or 1 | 0 | -Include additional information in the result if available, -e.g. wikipedia link, opening hours. (Default: 0) +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. -* `namedetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| namedetails | 0 or 1 | 0 | -Include a list of alternative names in the results. These may include -language variants, references, operator and brand. (Default: 0) +When set to 1, include a full list of names for the result. These may include +language variants, older names, references and brand. ### Language of results -* `accept-language=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| accept-language | browser language string | content of "Accept-Language" HTTP header | -Preferred language order for showing search results, overrides the value -specified in the "Accept-Language" HTTP header. -Either use a standard RFC2616 accept-language string or a simple -comma-separated list of language codes. +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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). -### Result limitation +!!! 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 contratry always + send the currently chosen browser language. -* `zoom=[0-18]` -Level of detail required for the address. Default: 18. This is a number that +### Result restriction + +| Parameter | Value | Default | +|-----------| ----- | ------- | +| zoom | 0-18 | 18 | + +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: @@ -95,41 +139,76 @@ In terms of address details the zoom levels are as follows: 12 | town / borough 13 | village / suburb 14 | neighbourhood - 15 | locality + 15 | any settlement 16 | major streets 17 | major and minor streets 18 | building +| Parameter | Value | Default | +|-----------| ----- | ------- | +| layers | comma-separated list of: `address`, `poi`, `railway`, `natural`, `manmade` | _unset_ (no restriction) | + +The layers 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 feautures like rivers, lakes and mountains while +the `manmade` layer functions as a catch-all for features not covered by the +other layers. + + ### Polygon output -* `polygon_geojson=1` -* `polygon_kml=1` -* `polygon_svg=1` -* `polygon_text=1` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | +| polygon_kml | 0 or 1 | 0 | +| polygon_svg | 0 or 1 | 0 | +| polygon_text | 0 or 1 | 0 | -Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these -options can be used at a time. (Default: 0) +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. -* `polygon_threshold=0.0` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_threshold | floating-point number | 0.0 | -Return a simplified version of the output geometry. The parameter is the +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 result. (Default: 0.0) +geometry. Topology is preserved in the geometry. + ### Other -* `email=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| email | valid email address | _unset_ | -If you are making a large number of requests, please include an appropriate email -address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. +If you are making large numbers of request please include an appropriate email +address to identify your requests. See Nominatim's +[Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. -* `debug=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| debug | 0 or 1 | 0 | Output assorted developer debug information. Data on internals of Nominatim's -"Search Loop" logic, and SQL queries. The output is (rough) HTML format. -This overrides the specified machine readable format. (Default: 0) +"search loop" logic, and SQL queries. The output is HTML format. +This overrides the specified machine readable format. ## Examples diff --git a/docs/api/Search.md b/docs/api/Search.md index b54c5302..a45ec36f 100644 --- a/docs/api/Search.md +++ b/docs/api/Search.md @@ -8,12 +8,12 @@ The search query may also contain 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. -!!! warning +!!! 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](https://overpass-api.de/). -## Parameters +## Endpoint The search API has the following format: @@ -21,35 +21,62 @@ The search API has the following format: https://nominatim.openstreetmap.org/search? ``` -The search term may be specified with two different sets of parameters: +!!! 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. -* `q=` +The query term can be given in two different forms: free-form or structured. - Free-form query string to search for. - 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](https://nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for - [birmingham, pilkington avenue](https://nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue). - Commas are optional, but improve performance by reducing the complexity of the search. +### Free-form query -* `amenity=` -* `street= ` -* `city=` -* `county=` -* `state=` -* `country=` -* `postalcode=` +| Parameter | Value | +|-----------| ----- | +| q | Free-form query string to search for | - Alternative query string format split into several parameters for structured requests. - Structured requests are faster but are less robust against alternative - OSM tagging schemas. **Do not combine with** `q=` **parameter**. +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](https://nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for +[birmingham, pilkington avenue](https://nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue). +Commas are optional, but improve performance by reducing the complexity of the search. -Both query forms accept the additional parameters listed below. +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 + +| Parameter | Value | +|----------- | ----- | +| amenity | name and/or type of POI | +| street | housenumber and streetname | +| city | city | +| county | county | +| state | state | +| country | country | +| postalcode | postal code | + +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=` parameter. Newer versions of + the API will return an error if you do so. Older versions simply return + unexpected results. + +## Parameters + +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 -* `format=[xml|json|jsonv2|geojson|geocodejson]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| format | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `jsonv2` | -See [Place Output Formats](Output.md) for details on each format. (Default: jsonv2) +See [Place Output Formats](Output.md) for details on each format. !!! note The Nominatim service at @@ -57,52 +84,148 @@ See [Place Output Formats](Output.md) for details on each format. (Default: json has a different default behaviour for historical reasons. When the `format` parameter is omitted, the request will be forwarded to the Web UI. -* `json_callback=` -Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `()`. +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | + +When given, then JSON output will be wrapped in a callback function with +the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more +information. + Only has an effect for JSON output formats. +| Parameter | Value | Default | +|-----------| ----- | ------- | +| limit | number | 10 | + +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 -* `addressdetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| addressdetails | 0 or 1 | 0 | -Include a breakdown of the address into elements. (Default: 0) +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. -* `extratags=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| extratags | 0 or 1 | 0 | -Include additional information in the result if available, -e.g. wikipedia link, opening hours. (Default: 0) +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. -* `namedetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| namedetails | 0 or 1 | 0 | -Include a list of alternative names in the results. These may include -language variants, references, operator and brand. (Default: 0) +When set to 1, include a full list of names for the result. These may include +language variants, older names, references and brand. ### Language of results -* `accept-language=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| accept-language | browser language string | content of "Accept-Language" HTTP header | -Preferred language order for showing search results, overrides the value -specified in the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). -Either use a standard RFC2616 accept-language string or a simple -comma-separated list of language codes. +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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). -### Result limitation +!!! 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 contratry always + send the currently chosen browser language. -* `countrycodes=[,][,]...` +### Result restriction -Limit search results to one or more countries. `` must be the -[ISO 3166-1alpha2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, -e.g. `gb` for the United Kingdom, `de` for Germany. +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. + +| Parameter | Value | Default | +|-----------| ----- | ------- | +| countrycodes | comma-separated list of country codes | _unset_ | + +Filer that limits the search results to one or more countries. +The country code must be the +[ISO 3166-1alpha2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 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, in international waters. +at all, for example, when it is in international waters. These places are +also excluded when the filter is set. -* `exclude_place_ids=,,,` | _unset_ | -* `limit=` +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. -Limit the number of returned results. (Default: 10, Maximum: 50) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| bounded | 0 or 1 | 0 | +When set to 1, then it turns the 'viewbox' parameter (see above) into +a filter paramter, excluding any results outside the viewbox. -* `viewbox=,,,` - -The preferred area to find search results. Any two corner points of the box -are accepted as long as they span a real box. `x` is longitude, -`y` is latitude. - - -* `bounded=[0|1]` - -When a viewbox is given, restrict the result to items contained within that -viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity -only search is allowed. Give the special keyword for the amenity in square +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 is complete. (Default: 0) +There is no guarantee that the result returns all objects in the area. ### Polygon output -* `polygon_geojson=1` -* `polygon_kml=1` -* `polygon_svg=1` -* `polygon_text=1` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | +| polygon_kml | 0 or 1 | 0 | +| polygon_svg | 0 or 1 | 0 | +| polygon_text | 0 or 1 | 0 | -Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these -options can be used at a time. (Default: 0) +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. -* `polygon_threshold=0.0` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_threshold | floating-point number | 0.0 | -Return a simplified version of the output geometry. The parameter is the +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 result. (Default: 0.0) +geometry. Topology is preserved in the geometry. ### Other -* `email=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| email | valid email address | _unset_ | If you are making large numbers of request please include an appropriate email -address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. +address to identify your requests. See Nominatim's +[Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. -* `dedupe=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| dedupe | 0 or 1 | 1 | 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 unless -this parameter is set to 0. (Default: 1) +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. -* `debug=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| debug | 0 or 1 | 0 | Output assorted developer debug information. Data on internals of Nominatim's -"Search Loop" logic, and SQL queries. The output is (rough) HTML format. -This overrides the specified machine readable format. (Default: 0) - +"search loop" logic, and SQL queries. The output is HTML format. +This overrides the specified machine readable format. ## Examples diff --git a/docs/api/Status.md b/docs/api/Status.md index 1a5ff0a8..a34c86c1 100644 --- a/docs/api/Status.md +++ b/docs/api/Status.md @@ -1,35 +1,50 @@ # Status -Useful for checking if the service and database is running. The JSON output also shows +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 + +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 -* `format=[text|json]` (defaults to 'text') +The status endpoint takes a single optional parameter: + +| Parameter | Value | Default | +|-----------| ----- | ------- | +| format | one of: `text`, `json` | 'text' | + +Selects the output format. See below. ## Output #### Text format -``` - https://nominatim.openstreetmap.org/status.php -``` +When everything is okay, a status code 200 is returned and a simple message: `OK` -will return HTTP status code 200 and print `OK`. - -On error it will return HTTP status code 500 and print a message, e.g. +On error it will return HTTP status code 500 and print a detailed error message, e.g. `ERROR: Database connection failed`. #### JSON format -``` - https://nominatim.openstreetmap.org/status.php?format=json -``` +Always returns a HTTP code 200, when the status call could be executed. -will return HTTP code 200 and a structure +On success a JSON dictionary with the following structure is returned: ```json { @@ -45,8 +60,8 @@ 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 also return HTTP status code 200 and a structure with error -code and message, e.g. +On error will return a shorter JSON dictionary with the error message +and status only, e.g. ```json { @@ -54,14 +69,3 @@ code and message, e.g. "message": "Database connection failed" } ``` - -Possible status codes are - -| | message | notes | -| --- | ------------------------------ | ----------------------------------------------------------------- | -| 700 | "No database" | connection failed | -| 701 | "Module failed" | database could not load nominatim.so | -| 702 | "Module call failed" | nominatim.so loaded but calling a function failed | -| 703 | "Query failed" | test query against a database table failed | -| 704 | "No value" | test query worked but returned no results | -| 705 | "Import date is not available" | No import dates were returned (enabling replication can fix this) | diff --git a/docs/customize/Settings.md b/docs/customize/Settings.md index ebfa2421..8245e309 100644 --- a/docs/customize/Settings.md +++ b/docs/customize/Settings.md @@ -91,7 +91,7 @@ The option is only used by the Legacy tokenizer and ignored otherwise. | -------------- | --------------------------------------------------- | | **Description:** | Tokenizer used for normalizing and parsing queries and names | | **Format:** | string | -| **Default:** | legacy | +| **Default:** | icu | | **After Changes:** | cannot be changed after import | Sets the tokenizer type to use for the import. For more information on @@ -148,29 +148,6 @@ Setting this option to 'yes' means that Nominatim skips reindexing of contained objects when the area becomes too large. -#### NOMINATIM_UPDATE_FORWARD_DEPENDENCIES - -| Summary | | -| -------------- | --------------------------------------------------- | -| **Description:** | Forward geometry changes to dependet objects | -| **Format:** | bool | -| **Default:** | no | -| **Comment:** | EXPERT ONLY. Must not be enabled after import. | - -The geometry of OSM ways and relations may change when a node that is part -of the object is moved around. These changes are not propagated per default. -The geometry of ways/relations is only updated the next time that the object -itself is touched. When enabling this option, then dependent objects will -be marked for update when one of its member objects changes. - -Enabling this option may slow down updates significantly. - -!!! warning - If you want to enable this option, it must be set already on import. - Do not enable this option on an existing database that was imported with - NOMINATIM_UPDATE_FORWARD_DEPENDENCIES=no. - Updates will become unusably slow. - #### NOMINATIM_LANGUAGES | Summary | | @@ -575,6 +552,8 @@ used. | **Format:** | boolean | | **Default:** | no | | **After Changes:** | run `nominatim refresh --website` | +| **Comment:** | PHP frontend only | + This feature is currently undocumented and potentially broken. @@ -587,6 +566,7 @@ This feature is currently undocumented and potentially broken. | **Format:** | integer | | **Default:** | 500 | | **After Changes:** | run `nominatim refresh --website` | +| **Comment:** | PHP frontend only | This setting defines the threshold over which a name is no longer considered as rare. When searching for places with rare names, only the name is used @@ -636,6 +616,7 @@ Setting this parameter to 0 disables polygon output completely. | **Format:** | boolean | | **Default:** | no | | **After Changes:** | run `nominatim refresh --website` | +| **Comment:** | PHP frontend only | Enable to search elements just within countries. @@ -644,6 +625,70 @@ finds a geometry of a region, do not return the geometry. Return "Unable to geocode" instead. +#### NOMINATIM_SERVE_LEGACY_URLS + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Enable serving via URLs with a .php suffix | +| **Format:** | boolean | +| **Default:** | yes | +| **Comment:** | Python frontend only | + +When enabled, then endpoints are reachable as `/` as well as `/.php`. +This can be useful when you want to be backwards-compatible with previous +versions of Nominatim. + + +#### NOMINATIM_API_POOL_SIZE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Number of parallel database connections per worker | +| **Format:** | number | +| **Default:** | 10 | +| **Comment:** | Python frontend only | + +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` * `` connections. +For configuring the number of workers, refer to the section about +[Deploying the Python frontend](../admin/Deployment-Python.md). + +#### NOMINATIM_QUERY_TIMEOUT + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Timeout for SQL queries to the database | +| **Format:** | number (seconds) | +| **Default:** | 10 | +| **Comment:** | Python frontend only | + +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](../library/Low-Level-DB-Access.md) +of the library. A timeout can be manually set, if required. + + +#### NOMINATIM_REQUEST_TIMEOUT + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Timeout for search queries | +| **Format:** | number (seconds) | +| **Default:** | 60 | +| **Comment:** | Python frontend only | + +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. + ### Logging Settings #### NOMINATIM_LOG_DB @@ -687,3 +732,20 @@ given in seconds and corresponds to the time the query took executing in PHP. type contains the name of the endpoint used. Can be used as the same time as NOMINATIM_LOG_DB. + +#### NOMINATIM_DEBUG_SQL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Enable printing of raw SQL by SQLAlchemy | +| **Format:** | boolean | +| **Default:** | no | +| **Comment:** | **For developers only.** | + +This settings enables +[SQL debugging](https://docs.sqlalchemy.org/en/20/core/engines.html#dbengine-logging) +by SQLAlchemy. This can be helpful when debugging some bugs with internal +query handling. It should only be used together with the CLI query functions. +Enabling it for server mode may have unintended consequences. Use the `debug` +parameter instead, which prints information on how the search is executed +including SQL statements. diff --git a/docs/customize/Tokenizers.md b/docs/customize/Tokenizers.md index 6199ea42..2c7b6878 100644 --- a/docs/customize/Tokenizers.md +++ b/docs/customize/Tokenizers.md @@ -176,66 +176,66 @@ The following is a list of sanitizers that are shipped with Nominatim. ##### split-name-list ::: nominatim.tokenizer.sanitizers.split_name_list - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy ##### strip-brace-terms ::: nominatim.tokenizer.sanitizers.strip_brace_terms - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy ##### tag-analyzer-by-language ::: nominatim.tokenizer.sanitizers.tag_analyzer_by_language - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy ##### clean-housenumbers ::: nominatim.tokenizer.sanitizers.clean_housenumbers - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy ##### clean-postcodes ::: nominatim.tokenizer.sanitizers.clean_postcodes - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy ##### clean-tiger-tags ::: nominatim.tokenizer.sanitizers.clean_tiger_tags - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy #### delete-tags ::: nominatim.tokenizer.sanitizers.delete_tags - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy #### tag-japanese ::: nominatim.tokenizer.sanitizers.tag_japanese - selection: + options: members: False - rendering: heading_level: 6 + docstring_section_style: spacy #### Token Analysis diff --git a/docs/develop/Development-Environment.md b/docs/develop/Development-Environment.md index d0369ea1..64306454 100644 --- a/docs/develop/Development-Environment.md +++ b/docs/develop/Development-Environment.md @@ -47,8 +47,8 @@ depending on your choice of webserver framework: The documentation is built with mkdocs: * [mkdocs](https://www.mkdocs.org/) >= 1.1.2 -* [mkdocstrings](https://mkdocstrings.github.io/) >= 0.16 -* [mkdocstrings-python-legacy](https://mkdocstrings.github.io/python-legacy/) +* [mkdocstrings](https://mkdocstrings.github.io/) >= 0.18 +* [mkdocstrings-python](https://mkdocstrings.github.io/python/) ### Installing prerequisites on Ubuntu/Debian diff --git a/docs/develop/ICU-Tokenizer-Modules.md b/docs/develop/ICU-Tokenizer-Modules.md index 2cf30a56..63b1c3c1 100644 --- a/docs/develop/ICU-Tokenizer-Modules.md +++ b/docs/develop/ICU-Tokenizer-Modules.md @@ -53,8 +53,7 @@ the function. ### Sanitizer configuration ::: nominatim.tokenizer.sanitizers.config.SanitizerConfig - rendering: - show_source: no + options: heading_level: 6 ### The main filter function of the sanitizer @@ -62,12 +61,10 @@ the function. The filter function receives a single object of type `ProcessInfo` which has with three members: - * `place`: read-only information about the place being processed. + * `place: PlaceInfo`: read-only information about the place being processed. See PlaceInfo below. - * `names`: The current list of names for the place. Each name is a - PlaceName object. - * `address`: The current list of address names for the place. Each name - is a PlaceName object. + * `names: List[PlaceName]`: The current list of names for the place. + * `address: List[PlaceName]`: The current list of address names for the place. While the `place` member is provided for information only, the `names` and `address` lists are meant to be manipulated by the sanitizer. It may add and @@ -77,16 +74,14 @@ adding extra attributes) or completely replace the list with a different one. #### PlaceInfo - information about the place ::: nominatim.data.place_info.PlaceInfo - rendering: - show_source: no + options: heading_level: 6 #### PlaceName - extended naming information ::: nominatim.data.place_name.PlaceName - rendering: - show_source: no + options: heading_level: 6 @@ -145,14 +140,12 @@ They can be found in the directory ## Custom token analysis module ::: nominatim.tokenizer.token_analysis.base.AnalysisModule - rendering: - show_source: no + options: heading_level: 6 ::: nominatim.tokenizer.token_analysis.base.Analyzer - rendering: - show_source: no + options: heading_level: 6 ### Example: Creating acronym variants for long names diff --git a/docs/develop/Tokenizers.md b/docs/develop/Tokenizers.md index eb0d4ea2..05037177 100644 --- a/docs/develop/Tokenizers.md +++ b/docs/develop/Tokenizers.md @@ -134,14 +134,14 @@ All tokenizers must inherit from `nominatim.tokenizer.base.AbstractTokenizer` and implement the abstract functions defined there. ::: nominatim.tokenizer.base.AbstractTokenizer - rendering: - heading_level: 4 + options: + heading_level: 6 ### Python Analyzer Class ::: nominatim.tokenizer.base.AbstractAnalyzer - rendering: - heading_level: 4 + options: + heading_level: 6 ### PL/pgSQL Functions diff --git a/docs/extra.css b/docs/extra.css index 3aecf2ef..155fa1aa 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -2,6 +2,10 @@ display: none!important } +.wy-nav-content { + max-width: 900px!important +} + table { margin-bottom: 12pt } @@ -16,9 +20,17 @@ th { .doc-object h6 { margin-bottom: 0.8em; - font-size: 120%; + font-size: 130%; } .doc-object { margin-bottom: 1.3em; } + +.doc-children .doc-contents { + margin-left: 3em; +} + +.md-footer__inner { + display: none; +} diff --git a/docs/index.md b/docs/index.md index 0ed6c546..0b479a17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,15 @@ -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). +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 four parts: +This guide comes in five parts: * __[API reference](api/Overview.md)__ for users of Nominatim * __[Administration Guide](admin/Installation.md)__ for those who want to install their own Nominatim server * __[Customization Guide](customize/Overview.md)__ for those who want to adapt their own installation to their special requirements + * __[Library Guide](library/Getting-Started.md)__ for Python developers who + want to use Nominatim as a library in their project * __[Developer's Guide](develop/overview.md)__ for developers of the software diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md new file mode 100644 index 00000000..b97c2ccd --- /dev/null +++ b/docs/library/Configuration.md @@ -0,0 +1,31 @@ +# Configuration + +When using Nominatim through the library, it can be configured in exactly +the same way as when running as a service. This means that you should have +created a [project directory](../admin/Import.md#creating-the-project-directory) +which contains all files belonging to the Nominatim instance. It can also contain +an `.env` file with configuration options. Setting configuration parameters +via environment variables works as well. + +Configuration options are resolved in the following order: + +* from the OS environment (or the dictionary given in `environ`, + (see NominatimAPI.md#nominatim.api.core.NominatimAPI.__init__) +* from the .env file in the project directory of the installation +* from the default installation in the configuration directory + +For more information on configuration via dotenv and a list of possible +configuration parameters, see the [Configuration page](../customize/Settings.md). + + +## `Configuration` class + +::: nominatim.config.Configuration + options: + members: + - get_bool + - get_int + - get_str_list + - get_path + heading_level: 6 + show_signature_annotations: True diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md new file mode 100644 index 00000000..88f25eb6 --- /dev/null +++ b/docs/library/Getting-Started.md @@ -0,0 +1,248 @@ +# Getting Started + +The Nominatim search frontend can directly be used as a Python library in +scripts and applications. When you have imported your own Nominatim database, +then it is no longer necessary to run a full web service for it and access +the database through http requests. There are +also less constraints on the kinds of data that can be accessed. The library +allows to get access to more detailed information about the objects saved +in the database. + +!!! danger + The library interface is currently in an experimental stage. There might + be some smaller adjustments to the public interface until the next version. + + The library also misses a proper installation routine, so some manipulation + of the PYTHONPATH is required. At the moment, use is only recommended for + developers wit some experience in Python. + +## Installation + +To use the Nominatim library, you need access to a local Nominatim database. +Follow the [installation and import instructions](../admin/) to set up your +database. + +It is not yet possible to install it in the usual way via pip or inside a +virtualenv. To get access to the library you need to set an appropriate +PYTHONPATH. With the default installation, the python library can be found +under `/usr/local/share/nominatim/lib-python`. If you have installed +Nominatim under a different prefix, adapt the `/usr/local/` part accordingly. +You can also point the PYTHONPATH to the Nominatim source code. + +### A simple search example + +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 if 'Brugge': + +!!! example + === "NominatimAPIAsync" + ``` python + from pathlib import Path + import asyncio + + import nominatim.api as napi + + async def search(query): + api = napi.NominatimAPIAsync(Path('.')) + + 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 + from pathlib import Path + + import nominatim.api as napi + + api = napi.NominatimAPI(Path('.')) + + 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](https://docs.python.org/3/library/asyncio.html). `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 + +The [Configuration](../admin/Import.md#configuration-setup-in-env) +section explains how Nominatim is configured using the +[dotenv](https://github.com/theskumar/python-dotenv) library. +The same configuration mechanism is used with the +Nominatim API library. You should therefore be sure you are familiar with +the section. + +The constructor of the 'Nominatim API class' takes one mandatory parameter: +the path to the [project directory](../admin/Import.md#creating-the-project-directory). +You should have set up this directory as part of the Nominatim import. +Any configuration found in the `.env` file in this directory will automatically +used. + +Yo may also configure Nominatim be setting environment variables. +Normally, Nominatim will check the operating system environment. This can be +overwritten by giving the constructor a dictionary of configuration parameters. + +Let us look up 'Brugge' in the special database named 'belgium' instead of the +standard 'nominatim' database: + +!!! example + === "NominatimAPIAsync" + ``` python + from pathlib import Path + import asyncio + + import nominatim.api as napi + + config_params = { + 'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium' + } + + async def search(query): + api = napi.NominatimAPIAsync(Path('.'), environ=config_params) + + return await api.search(query) + + results = asyncio.run(search('Brugge')) + ``` + + === "NominatimAPI" + ``` python + from pathlib import Path + + import nominatim.api as napi + + config_params = { + 'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium' + } + + api = napi.NominatimAPI(Path('.'), environ=config_params) + + results = api.search('Brugge') + ``` + +### Presenting results to humans + +All search functions return the raw results from the database. There is no +full human-readable label. To create such a label, you need two things: + +* the address details of the place +* adapt the result to the language you wish to use for display + +Again searching for 'Brugge', this time with a nicely formatted result: + +!!! example + === "NominatimAPIAsync" + ``` python + from pathlib import Path + import asyncio + + import nominatim.api as napi + + async def search(query): + api = napi.NominatimAPIAsync(Path('.')) + + 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 + from pathlib import Path + + import nominatim.api as napi + + api = napi.NominatimAPI(Path('.')) + + 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: + +``` python +>>> 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 `Locale` 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 + +``` python +locale = napi.Locale(['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 Locale object can be applied to a name dictionary to return the best-matching +name out of it: + +``` python +>>> print(locale.display_name(results[0].names)) +'Brugges' +``` + +The `address_row` field has a helper function to apply the function to all +its members and save the result in the `local_name` field. It also returns +all the localized names as a convenient simple list. This list can be used +to create a human-readable output: + +``` python +>>> address_parts = results[0].address_rows.localize(locale) +>>> 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 `adlin_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](Result-Handling.md#detailed-address-description). diff --git a/docs/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md new file mode 100644 index 00000000..9227dc32 --- /dev/null +++ b/docs/library/Input-Parameter-Types.md @@ -0,0 +1,62 @@ +# Input Parameter Types + +This page describes in more detail some of the input parameter types used +in the query functions of the API object. + +## Place identification + +The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and +[lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions +require references to places in the database. Below the possible +types for place identification are listed. All types are dataclasses. + +### PlaceID + +::: nominatim.api.PlaceID + options: + heading_level: 6 + +### OsmID + +::: nominatim.api.OsmID + options: + heading_level: 6 + +## Geometry types + +::: nominatim.api.GeometryFormat + options: + heading_level: 6 + members_order: source + +## Geometry input + +### Point + +::: nominatim.api.Point + options: + heading_level: 6 + show_signature_annotations: True + +### Bbox + +::: nominatim.api.Bbox + options: + heading_level: 6 + show_signature_annotations: True + members_order: source + group_by_category: False + +## Layers + +Layers allow to restrict the search result to thematic groups. This is +orthogonal to restriction by address ranks, which groups places by their +geographic extent. + + +::: nominatim.api.DataLayer + options: + heading_level: 6 + members_order: source + + diff --git a/docs/library/Low-Level-DB-Access.md b/docs/library/Low-Level-DB-Access.md new file mode 100644 index 00000000..acd93fd1 --- /dev/null +++ b/docs/library/Low-Level-DB-Access.md @@ -0,0 +1,56 @@ +# Low-level connections + +The `NominatimAPIAsync` class allows to directly access the underlying +database connection to explore the raw data. Nominatim uses +[SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please +refer to the documentation of the library to understand how to write SQL. + +To get access to a search connection, use the `begin()` function of your +API object. This returns a `SearchConnection` object described below +wrapped in a context manager. Its +`t` property has definitions for all Nominatim search tables. For an +overview of available tables, refer to the +[Development Layout](../develop/Database-Layout.md) in in the development +chapter. Note that only tables that are needed for search are accessible +as SQLAlchemy tables. + +!!! warning + The database layout is not part of the API definition and may change + without notice. If you play with the low-level access functions, you + need to be prepared for such changes. + +Here is a simple example, which prints how many places are available in +the placex table: + +``` +import asyncio +from pathlib import Path +import sqlalchemy as sa +from nominatim.api import NominatimAPIAsync + +async def print_table_size(): + api = NominatimAPIAsync(Path('.')) + + async with api.begin() as conn: + cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex)) + print(f'placex table has {cnt} rows.') + +asyncio.run(print_table_size()) +``` + +!!! warning + Low-level connections may only be used to read data from the database. + Do not use it to add or modify data or you might break Nominatim's + normal functions. + +## SearchConnection class + +::: nominatim.api.SearchConnection + options: + members: + - scalar + - execute + - get_class_table + - get_db_property + - get_property + heading_level: 6 diff --git a/docs/library/NominatimAPI.md b/docs/library/NominatimAPI.md new file mode 100644 index 00000000..0fa9d659 --- /dev/null +++ b/docs/library/NominatimAPI.md @@ -0,0 +1,36 @@ +# The Nominatim API classes + +The API classes are the core object of the search library. Always instantiate +one of these classes first. The API classes are **not threadsafe**. You need +to instantiate a separate instance for each thread. + +### NominatimAPI + +::: nominatim.api.NominatimAPI + options: + members: + - __init__ + - config + - close + - status + - details + - lookup + - reverse + - search + - search_address + - search_category + heading_level: 6 + group_by_category: False + + +### NominatimAPIAsync + +::: nominatim.api.NominatimAPIAsync + options: + members: + - __init__ + - setup_database + - close + - begin + heading_level: 6 + group_by_category: False diff --git a/docs/library/Result-Handling.md b/docs/library/Result-Handling.md new file mode 100644 index 00000000..e2803f9f --- /dev/null +++ b/docs/library/Result-Handling.md @@ -0,0 +1,58 @@ +# Result handling + +The search functions of the Nominatim API always return a result object +with the raw information about the place that is available in the +database. This section discusses data types used in the results and utility +functions that allow further processing of the results. + +## Result fields + +### Sources + +Nominatim takes the result data from multiple sources. The `source_table` field +in the result describes, from which source the result was retrieved. + +::: nominatim.api.SourceTable + options: + heading_level: 6 + members_order: source + +### Detailed address description + +When the `address_details` parameter is set, then functions return not +only information about the result place but also about the place that +make up the address. This information is almost always required when you +want to present the user with a human-readable description of the result. +See also [Localization](#localization) below. + +The address details are available in the `address_rows` field as a ordered +list of `AddressLine` objects with the country information last. The list also +contains the result place itself and some artificial entries, for example, +for the house number or the country code. This makes processing and creating +a full address easier. + +::: nominatim.api.AddressLine + options: + heading_level: 6 + members_order: source + +### Detailed search terms + +The `details` function can return detailed information about which search terms +may be used to find a place, when the `keywords` parameter is set. Search +terms are split into terms for the name of the place and search terms for +its address. + +::: nominatim.api.WordInfo + options: + heading_level: 6 + +## Localization + +Results are always returned with the full list of available names. + +### Locale + +::: nominatim.api.Locales + options: + heading_level: 6 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c2a8d393..3301356d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,9 @@ -site_name: Nominatim Documentation -theme: readthedocs +site_name: Nominatim Manual +theme: + name: material + features: + - navigation.tabs +copyright: Copyright © Nominatim developer community docs_dir: ${CMAKE_CURRENT_BINARY_DIR} site_url: https://nominatim.org repo_url: https://github.com/openstreetmap/Nominatim @@ -18,7 +22,8 @@ nav: - 'Basic Installation': 'admin/Installation.md' - 'Import' : 'admin/Import.md' - 'Update' : 'admin/Update.md' - - 'Deploy' : 'admin/Deployment.md' + - 'Deploy (PHP frontend)' : 'admin/Deployment-PHP.md' + - 'Deploy (Python frontend)' : 'admin/Deployment-Python.md' - 'Nominatim UI' : 'admin/Setup-Nominatim-UI.md' - 'Advanced Installations' : 'admin/Advanced-Installations.md' - 'Maintenance' : 'admin/Maintenance.md' @@ -35,6 +40,13 @@ nav: - 'Special Phrases': 'customize/Special-Phrases.md' - 'External data: US housenumbers from TIGER': 'customize/Tiger.md' - 'External data: Postcodes': 'customize/Postcodes.md' + - 'Library Guide': + - 'Getting Started': 'library/Getting-Started.md' + - 'Nominatim API class': 'library/NominatimAPI.md' + - 'Configuration': 'library/Configuration.md' + - 'Input Parameter Types': 'library/Input-Parameter-Types.md' + - 'Result Handling': 'library/Result-Handling.md' + - 'Low-level DB Access': 'library/Low-Level-DB-Access.md' - 'Developers Guide': - 'Architecture Overview' : 'develop/overview.md' - 'Database Layout' : 'develop/Database-Layout.md' @@ -51,6 +63,8 @@ markdown_extensions: - codehilite - admonition - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true - def_list - toc: permalink:  @@ -59,7 +73,8 @@ plugins: - search - mkdocstrings: handlers: - python-legacy: - rendering: - show_source: false - show_signature_annotations: false + python: + paths: ["${PROJECT_SOURCE_DIR}"] + options: + show_source: False + show_bases: False diff --git a/nominatim/api/core.py b/nominatim/api/core.py index 0f1dd715..fe7cfa3a 100644 --- a/nominatim/api/core.py +++ b/nominatim/api/core.py @@ -30,11 +30,31 @@ from nominatim.api.results import DetailedResult, ReverseResult, SearchResults class NominatimAPIAsync: - """ API loader asynchornous version. + """ The main frontend to the Nominatim database implements the + functions for lookup, forward and reverse geocoding using + asynchronous functions. + + This class shares most of the functions with its synchronous + version. There are some additional functions or parameters, + which are documented below. """ def __init__(self, project_dir: Path, environ: Optional[Mapping[str, str]] = None, loop: Optional[asyncio.AbstractEventLoop] = None) -> None: + """ Initiate a new frontend object with synchronous API functions. + + Parameters: + project_dir: Path to the + [project directory](../admin/Import.md#creating-the-project-directory) + of the local Nominatim installation. + environ: Mapping of [configuration parameters](../customize/Settings.md). + When set, replaces any configuration via environment variables. + Settings in this mapping also have precedence over any + parameters found in the `.env` file of the project directory. + loop: The asyncio event loop that will be used when calling + functions. Only needed, when a custom event loop is used + and the Python version is 3.9 or earlier. + """ self.config = Configuration(project_dir, environ) self.query_timeout = self.config.get_int('QUERY_TIMEOUT') \ if self.config.QUERY_TIMEOUT else None @@ -50,7 +70,7 @@ class NominatimAPIAsync: async def setup_database(self) -> None: - """ Set up the engine and connection parameters. + """ Set up the SQL engine and connections. This function will be implicitly called when the database is accessed for the first time. You may also call it explicitly to @@ -288,19 +308,33 @@ class NominatimAPIAsync: class NominatimAPI: - """ API loader, synchronous version. + """ This class provides a thin synchronous wrapper around the asynchronous + Nominatim functions. It creates its own event loop and runs each + synchronous function call to completion using that loop. """ def __init__(self, project_dir: Path, environ: Optional[Mapping[str, str]] = None) -> None: + """ Initiate a new frontend object with synchronous API functions. + + Parameters: + project_dir: Path to the + [project directory](../admin/Import.md#creating-the-project-directory) + of the local Nominatim installation. + environ: Mapping of [configuration parameters](../customize/Settings.md). + When set, replaces any configuration via environment variables. + Settings in this mapping also have precedence over any + parameters found in the `.env` file of the project directory. + """ self._loop = asyncio.new_event_loop() self._async_api = NominatimAPIAsync(project_dir, environ, loop=self._loop) def close(self) -> None: - """ Close all active connections to the database. The NominatimAPIAsync - object remains usable after closing. If a new API functions is - called, new connections are created. + """ Close all active connections to the database. + + This function also closes the asynchronous worker loop making + the NominatimAPI object unusuable. """ self._loop.run_until_complete(self._async_api.close()) self._loop.close() @@ -308,18 +342,109 @@ class NominatimAPI: @property def config(self) -> Configuration: - """ Return the configuration used by the API. + """ Provide read-only access to the [configuration](#Configuration) + used by the API. """ return self._async_api.config def status(self) -> StatusResult: - """ Return the status of the database. + """ Return the status of the database as a dataclass object + with the fields described below. + + Returns: + status(int): A status code as described on the status page. + message(str): Either 'OK' or a human-readable message of the + problem encountered. + software_version(tuple): A tuple with the version of the + Nominatim library consisting of (major, minor, patch, db-patch) + version. + database_version(tuple): A tuple with the version of the library + which was used for the import or last migration. + Also consists of (major, minor, patch, db-patch). + data_updated(datetime): Timestamp with the age of the data. """ return self._loop.run_until_complete(self._async_api.status()) def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]: """ Get detailed information about a place in the database. + + The result is a dataclass object with the fields described below + or `None` if the place could not be found in the database. + + Parameters: + place: Description of the place to look up. See + [Place identification](Input-Parameter-Types.md#place-identification) + for the various ways to reference a place. + + Other parameters: + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + parent_place_id (Optional(int]): Internal ID of the parent of this + place. Only meaning full for POI-like objects (places with a + rank_address of 30). + linked_place_id (Optional[int]): Internal ID of the place this object + linkes to. When this ID is set then there is no guarantee that + the rest of the result information is complete. + admin_level (int): Value of the `admin_level` OSM tag. Only meaningful + for administrative boundary objects. + indexed_date (datetime): Timestamp when the place was last updated. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. """ return self._loop.run_until_complete(self._async_api.details(place, **params)) @@ -328,6 +453,75 @@ class NominatimAPI: """ Get simple information about a list of places. Returns a list of place information for all IDs that were found. + Each result is a dataclass with the fields detailed below. + + Parameters: + places: List of descriptions of the place to look up. See + [Place identification](Input-Parameter-Types.md#place-identification) + for the various ways to reference a place. + + Other parameters: + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + bbox (Bbox): Bounding box of the full geometry of the place. + If the place is a single point, then the size of the bounding + box is guessed according to the type of place. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. """ return self._loop.run_until_complete(self._async_api.lookup(places, **params)) @@ -335,14 +529,180 @@ class NominatimAPI: def reverse(self, coord: ntyp.AnyPoint, **params: Any) -> Optional[ReverseResult]: """ Find a place by its coordinates. Also known as reverse geocoding. - Returns the closest result that can be found or None if - no place matches the given criteria. + Returns the closest result that can be found or `None` if + no place matches the given criteria. The result is a dataclass + with the fields as detailed below. + + Parameters: + coord: Coordinate to lookup the place for as a Point + or a tuple (x, y). Must be in WGS84 projection. + + Other parameters: + max_rank (int): Highest address rank to return. Can be used to + restrict search to streets or settlements. + layers (enum): Defines the kind of data to take into account. + See description of layers below. (Default: addresses and POIs) + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + bbox (Bbox): Bounding box of the full geometry of the place. + If the place is a single point, then the size of the bounding + box is guessed according to the type of place. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. + distance (Optional[float]): Distance in degree from the input point. """ return self._loop.run_until_complete(self._async_api.reverse(coord, **params)) def search(self, query: str, **params: Any) -> SearchResults: """ Find a place by free-text search. Also known as forward geocoding. + + Parameters: + query: Free-form text query searching for a place. + + Other parameters: + max_results (int): Maximum number of results to return. The + actual number of results may be less. (Default: 10) + min_rank (int): Lowest permissible rank for the result. + For addressable places this is the minimum + [address rank](../customize/Ranking.md#address-rank). For all + other places the [search rank](../customize/Ranking.md#search-rank) + is used. + max_rank (int): Highest permissible rank for the result. See min_rank above. + layers (enum): Defines the kind of data to take into account. + See [layers section](Input-Parameter-Types.md#layers) for details. + (Default: addresses and POIs) + countries (list[str]): Restrict search to countries with the given + ISO 3166-1 alpha-2 country code. An empty list (the default) + disables this filter. + excluded (list[int]): A list of internal IDs of places to exclude + from the search. + viewbox (Optional[Bbox]): Bounding box of an area to focus search on. + bounded_viewbox (bool): Consider the bounding box given in `viewbox` + as a filter and return only results within the bounding box. + near (Optional[Point]): Focus search around the given point and + return results ordered by distance to the given point. + near_radius (Optional[float]): Restrict results to results within + the given distance in degrees of `near` point. Ignored, when + `near` is not set. + categories (list[tuple]): Restrict search to places of the given + categories. The category is the main OSM tag assigned to each + place. An empty list (the default) disables this filter. + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + bbox (Bbox): Bounding box of the full geometry of the place. + If the place is a single point, then the size of the bounding + box is guessed according to the type of place. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. """ return self._loop.run_until_complete( self._async_api.search(query, **params)) @@ -358,6 +718,109 @@ class NominatimAPI: postalcode: Optional[str] = None, **params: Any) -> SearchResults: """ Find an address using structured search. + + Parameters: + amenity: Name of a POI. + street: Street and optionally housenumber of the address. If the address + does not have a street, then the place the housenumber references to. + city: Postal city of the address. + county: County equivalent of the address. Does not exist in all + jurisdictions. + state: State or province of the address. + country: Country with its full name or its ISO 3166-1 alpha-2 country code. + Do not use together with the country_code filter. + postalcode: Post code or ZIP for the place. + + Other parameters: + max_results (int): Maximum number of results to return. The + actual number of results may be less. (Default: 10) + min_rank (int): Lowest permissible rank for the result. + For addressable places this is the minimum + [address rank](../customize/Ranking.md#address-rank). For all + other places the [search rank](../customize/Ranking.md#search-rank) + is used. + max_rank (int): Highest permissible rank for the result. See min_rank above. + layers (enum): Defines the kind of data to take into account. + See [layers section](Input-Parameter-Types.md#layers) for details. + (Default: addresses and POIs) + countries (list[str]): Restrict search to countries with the given + ISO 3166-1 alpha-2 country code. An empty list (the default) + disables this filter. Do not use, when the country parameter + is used. + excluded (list[int]): A list of internal IDs of places to exclude + from the search. + viewbox (Optional[Bbox]): Bounding box of an area to focus search on. + bounded_viewbox (bool): Consider the bounding box given in `viewbox` + as a filter and return only results within the bounding box. + near (Optional[Point]): Focus search around the given point and + return results ordered by distance to the given point. + near_radius (Optional[float]): Restrict results to results within + the given distance in degrees of `near` point. Ignored, when + `near` is not set. + categories (list[tuple]): Restrict search to places of the given + categories. The category is the main OSM tag assigned to each + place. An empty list (the default) disables this filter. + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + bbox (Bbox): Bounding box of the full geometry of the place. + If the place is a single point, then the size of the bounding + box is guessed according to the type of place. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. """ return self._loop.run_until_complete( self._async_api.search_address(amenity, street, city, county, @@ -368,9 +831,104 @@ class NominatimAPI: near_query: Optional[str] = None, **params: Any) -> SearchResults: """ Find an object of a certain category near another place. + The near place may either be given as an unstructured search query in itself or as a geographic area through the viewbox or near parameters. + + Parameters: + categories: Restrict search to places of the given + categories. The category is the main OSM tag assigned to each + place. + near_query: Optional free-text query to define the are to + restrict search to. + + Other parameters: + max_results (int): Maximum number of results to return. The + actual number of results may be less. (Default: 10) + min_rank (int): Lowest permissible rank for the result. + For addressable places this is the minimum + [address rank](../customize/Ranking.md#address-rank). For all + other places the [search rank](../customize/Ranking.md#search-rank) + is used. + max_rank (int): Highest permissible rank for the result. See min_rank above. + layers (enum): Defines the kind of data to take into account. + See [layers section](Input-Parameter-Types.md#layers) for details. + (Default: addresses and POIs) + countries (list[str]): Restrict search to countries with the given + ISO 3166-1 alpha-2 country code. An empty list (the default) + disables this filter. + excluded (list[int]): A list of internal IDs of places to exclude + from the search. + viewbox (Optional[Bbox]): Bounding box of an area to focus search on. + bounded_viewbox (bool): Consider the bounding box given in `viewbox` + as a filter and return only results within the bounding box. + near (Optional[Point]): Focus search around the given point and + return results ordered by distance to the given point. + near_radius (Optional[float]): Restrict results to results within + the given distance in degrees of `near` point. Ignored, when + `near` is not set. + geometry_output (enum): Add the full geometry of the place to the result. + Multiple formats may be selected. Note that geometries can become + quite large. (Default: none) + geometry_simplification (float): Simplification factor to use on + the geometries before returning them. The factor expresses + the tolerance in degrees from which the geometry may differ. + Topology is preserved. (Default: 0.0) + address_details (bool): Add detailed information about the places + that make up the address of the requested object. (Default: False) + linked_places (bool): Add detailed information about the places + that link to the result. (Default: False) + parented_places (bool): Add detailed information about all places + for which the requested object is a parent, i.e. all places for + which the object provides the address details. + Only POI places can have parents. (Default: False) + keywords (bool): Add detailed information about the search terms + used for this place. + + Returns: + source_table (enum): Data source of the place. See below for possible values. + category (tuple): A tuple of two strings with the primary OSM tag + and value. + centroid (Point): Point position of the place. + place_id (Optional[int]): Internal ID of the place. This ID may differ + for the same place between different installations. + osm_object (Optional[tuple]): OSM type and ID of the place, if available. + names (Optional[dict]): Dictionary of names of the place. Keys are + usually the corresponding OSM tag keys. + address (Optional[dict]): Dictionary of address parts directly + attributed to the place. Keys are usually the corresponding + OSM tag keys with the `addr:` prefix removed. + extratags (Optional[dict]): Dictionary of additional attributes for + the place. Usually OSM tag keys and values. + housenumber (Optional[str]): House number of the place, normalised + for lookup. To get the house number in its original spelling, + use `address['housenumber']`. + postcode (Optional[str]): Computed postcode for the place. To get + directly attributed postcodes, use `address['postcode']` instead. + wikipedia (Optional[str]): Reference to a wikipedia site for the place. + The string has the format :. + rank_address (int): [Address rank](../customize/Ranking.md#address-rank). + rank_search (int): [Search rank](../customize/Ranking.md#search-rank). + importance (Optional[float]): Relative importance of the place. This is a measure + how likely the place will be searched for. + country_code (Optional[str]): Country the feature is in as + ISO 3166-1 alpha-2 country code. + address_rows (Optional[AddressLines]): List of places that make up the + computed address. `None` when `address_details` parameter was False. + linked_rows (Optional[AddressLines]): List of places that link to the object. + `None` when `linked_places` parameter was False. + parented_rows (Optional[AddressLines]): List of direct children of the place. + `None` when `parented_places` parameter was False. + name_keywords (Optional[WordInfos]): List of search words for the name of + the place. `None` when `keywords` parameter is set to False. + address_keywords (Optional[WordInfos]): List of search word for the address of + the place. `None` when `keywords` parameter is set to False. + bbox (Bbox): Bounding box of the full geometry of the place. + If the place is a single point, then the size of the bounding + box is guessed according to the type of place. + geometry (dict): Dictionary containing the full geometry of the place + in the formats requested in the `geometry_output` parameter. """ return self._loop.run_until_complete( self._async_api.search_category(categories, near_query, **params)) diff --git a/nominatim/api/results.py b/nominatim/api/results.py index d425ff6c..0183f5b9 100644 --- a/nominatim/api/results.py +++ b/nominatim/api/results.py @@ -46,32 +46,88 @@ def _mingle_name_tags(names: Optional[Dict[str, str]]) -> Optional[Dict[str, str class SourceTable(enum.Enum): - """ Enumeration of kinds of results. + """ The `SourceTable` type lists the possible sources a result can have. """ PLACEX = 1 + """ The placex table is the main source for result usually containing + OSM data. + """ OSMLINE = 2 + """ The osmline table contains address interpolations from OSM data. + Interpolation addresses are always approximate. The OSM id in the + result refers to the OSM way with the interpolation line object. + """ TIGER = 3 + """ TIGER address data contains US addresses imported on the side, + see [Installing TIGER data](../customize/Tiger.md). + TIGER address are also interpolations. The addresses always refer + to a street from OSM data. The OSM id in the result refers to + that street. + """ POSTCODE = 4 + """ The postcode table contains artificial centroids for postcodes, + computed from the postcodes available with address points. Results + are always approximate. + """ COUNTRY = 5 + """ The country table provides a fallback, when country data is missing + in the OSM data. + """ @dataclasses.dataclass class AddressLine: - """ Detailed information about a related place. + """ The `AddressLine` may contain the following fields about a related place + and its function as an address object. Most fields are optional. + Their presence depends on the kind and function of the address part. """ place_id: Optional[int] + """ Internal ID of the place. + """ osm_object: Optional[Tuple[str, int]] + """ OSM type and ID of the place, if such an object exists. + """ category: Tuple[str, str] + """ Main category of the place, described by a key-value pair. + """ names: Dict[str, str] + """ All available names for the place including references, alternative + names and translations. + """ extratags: Optional[Dict[str, str]] + """ Any extra information available about the place. This is a dictionary + that usually contains OSM tag key-value pairs. + """ admin_level: Optional[int] + """ The administrative level of a boundary as tagged in the input data. + This field is only meaningful for places of the category + (boundary, administrative). + """ fromarea: bool + """ If true, then the exact area of the place is known. Without area + information, Nominatim has to make an educated guess if an address + belongs to one place or another. + """ isaddress: bool + """ If true, this place should be considered for the final address display. + Nominatim will sometimes include more than one candidate for + the address in the list when it cannot reliably determine where the + place belongs. It will consider names of all candidates when searching + but when displaying the result, only the most likely candidate should + be shown. + """ rank_address: int + """ [Address rank](../customize/Ranking.md#address-rank) of the place. + """ distance: float + """ Distance in degrees between the result place and this address part. + """ local_name: Optional[str] = None + """ Place holder for localization of this address part. See + [Localization](#localization) below. + """ class AddressLines(List[AddressLine]): @@ -80,7 +136,7 @@ class AddressLines(List[AddressLine]): def localize(self, locales: Locales) -> List[str]: """ Set the local name of address parts according to the chosen - locale. Return the list of local names without duplications. + locale. Return the list of local names without duplicates. Only address parts that are marked as isaddress are localized and returned. @@ -99,11 +155,19 @@ class AddressLines(List[AddressLine]): @dataclasses.dataclass class WordInfo: - """ Detailed information about a search term. + """ Each entry in the list of search terms contains the + following detailed information. """ word_id: int + """ Internal identifier for the word. + """ word_token: str + """ Normalised and transliterated form of the word. + This form is used for searching. + """ word: Optional[str] = None + """ Untransliterated form, if available. + """ WordInfos = Sequence[WordInfo] diff --git a/nominatim/api/types.py b/nominatim/api/types.py index a2a265c0..c96b3f59 100644 --- a/nominatim/api/types.py +++ b/nominatim/api/types.py @@ -22,18 +22,40 @@ from nominatim.errors import UsageError @dataclasses.dataclass class PlaceID: - """ Reference an object by Nominatim's internal ID. + """ Reference a place by Nominatim's internal ID. + + A PlaceID may reference place from the main table placex, from + the interpolation tables or the postcode tables. Place IDs are not + stable between installations. You may use this type theefore only + with place IDs obtained from the same database. """ place_id: int + """ + The internal ID of the place to reference. + """ @dataclasses.dataclass class OsmID: - """ Reference by the OSM ID and potentially the basic category. + """ Reference a place by its OSM ID and potentially the basic category. + + The OSM ID may refer to places in the main table placex and OSM + interpolation lines. """ osm_type: str + """ OSM type of the object. Must be one of `N`(node), `W`(way) or + `R`(relation). + """ osm_id: int + """ The OSM ID of the object. + """ osm_class: Optional[str] = None + """ The same OSM object may appear multiple times in the database under + different categories. The optional class parameter allows to distinguish + the different categories and corresponds to the key part of the category. + If there are multiple objects in the database and `osm_class` is + left out, then one of the objects is returned at random. + """ def __post_init__(self) -> None: if self.osm_type not in ('N', 'W', 'R'): @@ -135,12 +157,15 @@ WKB_BBOX_HEADER_LE = b'\x01\x03\x00\x00\x20\xE6\x10\x00\x00\x01\x00\x00\x00\x05\ WKB_BBOX_HEADER_BE = b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05' class Bbox: - """ A bounding box in WSG84 projection. + """ A bounding box in WGS84 projection. The coordinates are available as an array in the 'coord' property in the order (minx, miny, maxx, maxy). """ def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None: + """ Create a new bounding box with the given coordinates in WGS84 + projection. + """ self.coords = (minx, miny, maxx, maxy) @@ -197,7 +222,7 @@ class Bbox: @staticmethod def from_wkb(wkb: Union[None, str, bytes]) -> 'Optional[Bbox]': """ Create a Bbox from a bounding box polygon as returned by - the database. Return s None if the input value is None. + the database. Returns `None` if the input value is None. """ if wkb is None: return None @@ -259,23 +284,60 @@ class Bbox: class GeometryFormat(enum.Flag): - """ Geometry output formats supported by Nominatim. + """ All search functions support returning the full geometry of a place in + various formats. The internal geometry is converted by PostGIS to + the desired format and then returned as a string. It is possible to + request multiple formats at the same time. """ NONE = 0 + """ No geometry requested. Alias for a empty flag. + """ GEOJSON = enum.auto() + """ + [GeoJSON](https://geojson.org/) format + """ KML = enum.auto() + """ + [KML](https://en.wikipedia.org/wiki/Keyhole_Markup_Language) format + """ SVG = enum.auto() + """ + [SVG](http://www.w3.org/TR/SVG/paths.html) format + """ TEXT = enum.auto() + """ + [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format + """ class DataLayer(enum.Flag): - """ Layer types that can be selected for reverse and forward search. + """ The `DataLayer` flag type defines the layers that can be selected + for reverse and forward search. + """ + ADDRESS = enum.auto() + """ The address layer contains all places relavant for addresses: + fully qualified addresses with a house number (or a house name equivalent, + for some addresses) and places that can be part of an address like + roads, cities, states. """ POI = enum.auto() - ADDRESS = enum.auto() + """ Layer for points of interest like shops, restaurants but also + recycling bins or postboxes. + """ RAILWAY = enum.auto() - MANMADE = enum.auto() + """ Layer with railway features including tracks and other infrastructure. + Note that in Nominatim's standard configuration, only very few railway + features are imported into the database. Thus a custom configuration + is required to make full use of this layer. + """ NATURAL = enum.auto() + """ Layer with natural features like rivers, lakes and mountains. + """ + MANMADE = enum.auto() + """ Layer with other human-made features and boundaries. This layer is + the catch-all and includes all features not covered by the other + layers. A typical example for this layer are national park boundaries. + """ def format_country(cc: Any) -> List[str]: @@ -419,7 +481,7 @@ class SearchDetails(LookupDetails): """ excluded: List[int] = dataclasses.field(default_factory=list, metadata={'transform': format_excluded}) - """ List of OSM objects to exclude from the results. Currenlty only + """ List of OSM objects to exclude from the results. Currently only works when the internal place ID is given. An empty list (the default) will disable this filter. """ diff --git a/nominatim/api/v1/server_glue.py b/nominatim/api/v1/server_glue.py index 95484c5b..24f2234b 100644 --- a/nominatim/api/v1/server_glue.py +++ b/nominatim/api/v1/server_glue.py @@ -453,6 +453,8 @@ async def search_endpoint(api: napi.NominatimAPIAsync, params: ASGIAdaptor) -> A helpers.feature_type_to_rank(params.get('featureType', '')) if params.get('featureType', None) is not None: details['layers'] = napi.DataLayer.ADDRESS + else: + details['layers'] = params.get_layers() # unstructured query parameters query = params.get('q', None) diff --git a/nominatim/config.py b/nominatim/config.py index 3a4c3a6b..3344a425 100644 --- a/nominatim/config.py +++ b/nominatim/config.py @@ -47,17 +47,15 @@ def flatten_config_list(content: Any, section: str = '') -> List[Any]: class Configuration: - """ Load and manage the project configuration. - - Nominatim uses dotenv to configure the software. Configuration options - are resolved in the following order: - - * from the OS environment (or the dictionary given in `environ`) - * from the .env file in the project directory of the installation - * from the default installation in the configuration directory + """ This class wraps access to the configuration settings + for the Nominatim instance in use. All Nominatim configuration options are prefixed with 'NOMINATIM_' to - avoid conflicts with other environment variables. + avoid conflicts with other environment variables. All settings can + be accessed as properties of the class under the same name as the + setting but with the `NOMINATIM_` prefix removed. In addition, there + are accessor functions that convert the setting values to types + other than string. """ def __init__(self, project_dir: Optional[Path], @@ -99,14 +97,29 @@ class Configuration: def get_bool(self, name: str) -> bool: """ Return the given configuration parameter as a boolean. - Values of '1', 'yes' and 'true' are accepted as truthy values, - everything else is interpreted as false. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + `True` for values of '1', 'yes' and 'true', `False` otherwise. """ return getattr(self, name).lower() in ('1', 'yes', 'true') def get_int(self, name: str) -> int: """ Return the given configuration parameter as an int. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + The configuration value converted to int. + + Raises: + ValueError: when the value is not a number. """ try: return int(getattr(self, name)) @@ -118,8 +131,17 @@ class Configuration: def get_str_list(self, name: str) -> Optional[List[str]]: """ Return the given configuration parameter as a list of strings. The values are assumed to be given as a comma-sparated list and - will be stripped before returning them. On empty values None - is returned. + will be stripped before returning them. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + (List[str]): The comma-split parameter as a list. The + elements are stripped of leading and final spaces before + being returned. + (None): The configuration parameter was unset or empty. """ raw = getattr(self, name) @@ -128,9 +150,16 @@ class Configuration: def get_path(self, name: str) -> Optional[Path]: """ Return the given configuration parameter as a Path. - If a relative path is configured, then the function converts this - into an absolute path with the project directory as root path. - If the configuration is unset, None is returned. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + (Path): A Path object of the parameter value. + If a relative path is configured, then the function converts this + into an absolute path with the project directory as root path. + (None): The configuration parameter was unset or empty. """ value = getattr(self, name) if not value: diff --git a/nominatim/tokenizer/base.py b/nominatim/tokenizer/base.py index f0fd9dd0..061cff36 100644 --- a/nominatim/tokenizer/base.py +++ b/nominatim/tokenizer/base.py @@ -53,8 +53,8 @@ class AbstractAnalyzer(ABC): Returns: The function returns the list of all tuples that could be - found for the given words. Each list entry is a tuple of - (original word, word token, word id). + found for the given words. Each list entry is a tuple of + (original word, word token, word id). """ @@ -118,7 +118,7 @@ class AbstractAnalyzer(ABC): Returns: A JSON-serialisable structure that will be handed into - the database via the `token_info` field. + the database via the `token_info` field. """ @@ -144,8 +144,6 @@ class AbstractTokenizer(ABC): tables should be skipped. This option is only required for migration purposes and can be safely ignored by custom tokenizers. - - TODO: can we move the init_db parameter somewhere else? """ @@ -197,8 +195,8 @@ class AbstractTokenizer(ABC): Returns: If an issue was found, return an error message with the - description of the issue as well as hints for the user on - how to resolve the issue. If everything is okay, return `None`. + description of the issue as well as hints for the user on + how to resolve the issue. If everything is okay, return `None`. """ @@ -236,8 +234,12 @@ class AbstractTokenizer(ABC): @abstractmethod def most_frequent_words(self, conn: Connection, num: int) -> List[str]: - """ Return a list of the `num` most frequent full words - in the database. + """ Return a list of the most frequent full words in the database. + + Arguments: + conn: Open connection to the database which may be used to + retrieve the words. + num: Maximum number of words to return. """ diff --git a/nominatim/tokenizer/sanitizers/config.py b/nominatim/tokenizer/sanitizers/config.py index 9b4f763a..79396a75 100644 --- a/nominatim/tokenizer/sanitizers/config.py +++ b/nominatim/tokenizer/sanitizers/config.py @@ -41,9 +41,9 @@ class SanitizerConfig(_BaseUserDict): Returns: If the parameter value is a simple string, it is returned as a - one-item list. If the parameter value does not exist, the given - default is returned. If the parameter value is a list, it is - checked to contain only strings before being returned. + one-item list. If the parameter value does not exist, the given + default is returned. If the parameter value is a list, it is + checked to contain only strings before being returned. """ values = self.data.get(param, None) @@ -94,10 +94,10 @@ class SanitizerConfig(_BaseUserDict): Returns: A regular expression pattern which can be used to - split a string. The regular expression makes sure that the - resulting names are stripped and that repeated delimiters - are ignored. It may still create empty fields on occasion. The - code needs to filter those. + split a string. The regular expression makes sure that the + resulting names are stripped and that repeated delimiters + are ignored. It may still create empty fields on occasion. The + code needs to filter those. """ delimiter_set = set(self.data.get('delimiters', default)) if not delimiter_set: @@ -133,8 +133,8 @@ class SanitizerConfig(_BaseUserDict): Returns: A filter function that takes a target string as the argument and - returns True if it fully matches any of the regular expressions - otherwise returns False. + returns True if it fully matches any of the regular expressions + otherwise returns False. """ filters = self.get_string_list(param) or default diff --git a/nominatim/tokenizer/token_analysis/base.py b/nominatim/tokenizer/token_analysis/base.py index 68046f96..c7ec61c9 100644 --- a/nominatim/tokenizer/token_analysis/base.py +++ b/nominatim/tokenizer/token_analysis/base.py @@ -28,8 +28,8 @@ class Analyzer(Protocol): Returns: ID string with a canonical form of the name. The string may - be empty, when the analyzer cannot analyze the name at all, - for example because the character set in use does not match. + be empty, when the analyzer cannot analyze the name at all, + for example because the character set in use does not match. """ def compute_variants(self, canonical_id: str) -> List[str]: @@ -42,13 +42,13 @@ class Analyzer(Protocol): Returns: A list of possible spelling variants. All strings must have - been transformed with the global normalizer and - transliterator ICU rules. Otherwise they cannot be matched - against the input by the query frontend. - The list may be empty, when there are no useful - spelling variants. This may happen when an analyzer only - usually outputs additional variants to the canonical spelling - and there are no such variants. + been transformed with the global normalizer and + transliterator ICU rules. Otherwise they cannot be matched + against the input by the query frontend. + The list may be empty, when there are no useful + spelling variants. This may happen when an analyzer only + usually outputs additional variants to the canonical spelling + and there are no such variants. """ @@ -74,8 +74,8 @@ class AnalysisModule(Protocol): Returns: A data object with configuration data. This will be handed - as is into the `create()` function and may be - used freely by the analysis module as needed. + as is into the `create()` function and may be + used freely by the analysis module as needed. """ def create(self, normalizer: Any, transliterator: Any, config: Any) -> Analyzer: @@ -92,5 +92,5 @@ class AnalysisModule(Protocol): Returns: A new analyzer instance. This must be an object that implements - the Analyzer protocol. + the Analyzer protocol. """ diff --git a/settings/env.defaults b/settings/env.defaults index ff0a7648..64a160c7 100644 --- a/settings/env.defaults +++ b/settings/env.defaults @@ -77,20 +77,10 @@ NOMINATIM_HTTP_PROXY_PASSWORD= # EXPERT ONLY. You should usually use the supplied osm2pgsql. NOMINATIM_OSM2PGSQL_BINARY= -# Directory where to find US Tiger data files to import. -# OBSOLETE: use `nominatim add-data --tiger-data ` to explicitly state -# the directory on import -NOMINATIM_TIGER_DATA_PATH= - # Directory where to find pre-computed Wikipedia importance files. # When unset, the data is expected to be located in the project directory. NOMINATIM_WIKIPEDIA_DATA_PATH= -# Configuration file for special phrase import. -# OBSOLETE: use `nominatim special-phrases --config ` or simply put -# a custom phrase-settings.json into your project directory. -NOMINATIM_PHRASE_CONFIG= - # Configuration file for rank assignments. NOMINATIM_ADDRESS_LEVEL_CONFIG=address-levels.json @@ -245,5 +235,5 @@ NOMINATIM_LOG_DB=no NOMINATIM_LOG_FILE= # Echo raw SQL from SQLAlchemy statements. -# Works only in command line/library use. +# EXPERT: Works only in command line/library use. NOMINATIM_DEBUG_SQL=no