safety-screen/Nominatim
1
0
Fork 0
forked from hans/Nominatim
Code Pull Requests Activity

fix typos and grammar issues

Browse Source
This commit is contained in:
Sarah Hoffmann
2023-08-29 12:14:44 +02:00
parent 3794080327
commit cafd8e2b1e
15 changed files with 64 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/admin/Deployment-PHP.md
View File

@@ -13,8 +13,8 @@ to run a web service. Please refer to the documentation of
for background information on configuring the services. for background information on configuring the services.
!!! Note !!! Note
Throughout this page, we assume that your Nominatim project directory is Throughout this page, we assume your Nominatim project directory is
located in `/srv/nominatim-project` and that you have installed Nominatim located in `/srv/nominatim-project` and you have installed Nominatim
using the default installation prefix `/usr/local`. If you have put it using the default installation prefix `/usr/local`. If you have put it
somewhere else, you need to adjust the commands and configuration somewhere else, you need to adjust the commands and configuration
accordingly. accordingly.

25
docs/admin/Deployment-Python.md
View File

@@ -1,16 +1,18 @@
# Deploying the Nominatim Python frontend # Deploying the Nominatim Python frontend
The Nominatim can be run as a Python-based web application. You have the 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/) choice between [Falcon](https://falcon.readthedocs.io/en/stable/)
and [Starlette](https://www.starlette.io/) as the ASGI framework. and [Starlette](https://www.starlette.io/) as the ASGI framework.
This section gives a quick overview on how to configure Nginx to server This section gives a quick overview on how to configure Nginx to serve
Nominatim. Please refer to the documentation of Nominatim. Please refer to the documentation of
[Nginx](https://nginx.org/en/docs/) for background information on how to configure it. [Nginx](https://nginx.org/en/docs/) for background information on how
to configure it.
!!! Note !!! Note
Throughout this page, we assume that your Nominatim project directory is Throughout this page, we assume your Nominatim project directory is
located in `/srv/nominatim-project` and that you have installed Nominatim located in `/srv/nominatim-project` and you have installed Nominatim
using the default installation prefix `/usr/local`. If you have put it using the default installation prefix `/usr/local`. If you have put it
somewhere else, you need to adjust the commands and configuration somewhere else, you need to adjust the commands and configuration
accordingly. accordingly.
@@ -21,7 +23,7 @@ Nominatim. Please refer to the documentation of
### Installing the required packages ### Installing the required packages
The recommended way to deploy Python ASGI application is to run The recommended way to deploy a Python ASGI application is to run
the ASGI runner (uvicorn)[https://uvicorn.org/] the ASGI runner (uvicorn)[https://uvicorn.org/]
together with (gunicorn)[https://gunicorn.org/] HTTP server. We use together with (gunicorn)[https://gunicorn.org/] HTTP server. We use
Falcon here as the web framework. Falcon here as the web framework.
@@ -38,7 +40,7 @@ virtualenv /srv/nominatim-venv
### Setting up Nominatim as a systemd job ### Setting up Nominatim as a systemd job
Next you need to set up the application that serves Nominatim. This is Next you need to set up the service that runs the Nominatim frontend. This is
easiest done with a systemd job. easiest done with a systemd job.
Create the following file `/etc/systemd/system/nominatim.service`: Create the following file `/etc/systemd/system/nominatim.service`:
@@ -55,9 +57,9 @@ Environment="PYTHONPATH=/usr/local/lib/nominatim/lib-python/"
User=www-data User=www-data
Group=www-data Group=www-data
WorkingDirectory=/srv/nominatim-project WorkingDirectory=/srv/nominatim-project
ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 14 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi 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 ExecReload=/bin/kill -s HUP $MAINPID
StandardOutput=append:/ssd/nominatim/log/gunicorn.log StandardOutput=append:/var/log/gunicorn-nominatim.log
StandardError=inherit StandardError=inherit
PrivateTmp=true PrivateTmp=true
TimeoutStopSec=5 TimeoutStopSec=5
@@ -67,6 +69,11 @@ KillMode=mixed
WantedBy=multi-user.target 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: Make the new service known to systemd and start it:
``` sh ``` sh

2
docs/admin/Import.md
View File

@@ -317,7 +317,7 @@ To run Nominatim via webservers like Apache or nginx, please continue reading
## Enabling search by category phrases ## Enabling search by category phrases
If you want to be able to search for places by their type using To be able to search for places by their type using
[special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
you also need to import these key phrases like this: you also need to import these key phrases like this:

7
docs/api/Details.md
View File

@@ -2,12 +2,11 @@
Show all details about a single place saved in the database. 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 This API endpoint is meant for visual inspection of the data in the database,
and is meant for use with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/). mainly together with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/).
The parameters of the endpoint and the output may change occasionally between 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. versions of Nominatim. Do not rely on the output in scripts or applications.
!!! warning !!! warning
The details endpoint at https://nominatim.openstreetmap.org The details endpoint at https://nominatim.openstreetmap.org
may not used in scripts or bots at all. may not used in scripts or bots at all.
@@ -56,7 +55,7 @@ This section lists additional optional parameters.
|-----------| ----- | ------- | |-----------| ----- | ------- |
| json_callback | function name | _unset_ | | json_callback | function name | _unset_ |
When given, then JSON output will be wrapped in a callback function with 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 the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more
information. information.

2
docs/api/Lookup.md
View File

@@ -114,7 +114,7 @@ options can be used at a time.
|-----------| ----- | ------- | |-----------| ----- | ------- |
| polygon_threshold | floating-point number | 0.0 | | polygon_threshold | floating-point number | 0.0 |
When one og the polygon_* outputs is chosen, return a simplified version When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry. geometry. Topology is preserved in the geometry.

12
docs/api/Reverse.md
View File

@@ -153,17 +153,17 @@ The layers filter allows to select places by themes.
The `address` layer contains all places that make up an address: The `address` layer contains all places that make up an address:
address points with house numbers, streets, inhabited places (suburbs, villages, address points with house numbers, streets, inhabited places (suburbs, villages,
cities, states tec.) and administrative boundaries. cities, states etc.) and administrative boundaries.
The `poi` layer selects all point of interest. This includes classic POIs like The `poi` layer selects all point of interest. This includes classic points
restaurants, shops, hotels but also less obvious features like recycling bins, of interest like restaurants, shops, hotels but also less obvious features
guideposts or benches. like recycling bins, guideposts or benches.
The `railway` layer includes railway infrastructure like tracks. The `railway` layer includes railway infrastructure like tracks.
Note that in Nominatim's standard configuration, only very few railway Note that in Nominatim's standard configuration, only very few railway
features are imported into the database. features are imported into the database.
The `natural` layer collects feautures like rivers, lakes and mountains. While 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 the `manmade` layer functions as a catch-all for features not covered by the
other layers. other layers.
@@ -185,7 +185,7 @@ options can be used at a time.
|-----------| ----- | ------- | |-----------| ----- | ------- |
| polygon_threshold | floating-point number | 0.0 | | polygon_threshold | floating-point number | 0.0 |
When one og the polygon_* outputs is chosen, return a simplified version When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry. geometry. Topology is preserved in the geometry.

6
docs/api/Search.md
View File

@@ -201,7 +201,7 @@ The `railway` layer includes railway infrastructure like tracks.
Note that in Nominatim's standard configuration, only very few railway Note that in Nominatim's standard configuration, only very few railway
features are imported into the database. features are imported into the database.
The `natural` layer collects feautures like rivers, lakes and mountains. While 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 the `manmade` layer functions as a catch-all for features not covered by the
other layers. other layers.
@@ -271,7 +271,7 @@ options can be used at a time.
|-----------| ----- | ------- | |-----------| ----- | ------- |
| polygon_threshold | floating-point number | 0.0 | | polygon_threshold | floating-point number | 0.0 |
When one og the polygon_* outputs is chosen, return a simplified version When one of the polygon_* outputs is chosen, return a simplified version
of the output geometry. The parameter describes the of the output geometry. The parameter describes the
tolerance in degrees with which the geometry may differ from the original tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the geometry. geometry. Topology is preserved in the geometry.
@@ -294,7 +294,7 @@ 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 object in reality. The simplest case is a street being split into many
different OSM ways due to different characteristics. Nominatim will different OSM ways due to different characteristics. Nominatim will
attempt to detect such duplicates and only return one match. Setting attempt to detect such duplicates and only return one match. Setting
this parameter is set to 0 disables this deduplication mechanism and this parameter to 0 disables this deduplication mechanism and
ensures that all results are returned. ensures that all results are returned.
| Parameter | Value | Default | | Parameter | Value | Default |

8
docs/customize/Settings.md
View File

@@ -650,8 +650,10 @@ versions of Nominatim.
Sets the maximum number of database connections available for a single instance Sets the maximum number of database connections available for a single instance
of Nominatim. When configuring the maximum number of connections that your of Nominatim. When configuring the maximum number of connections that your
PostgreSQL database can handle, you need at least `<pool size> * <worker>` PostgreSQL database can handle, you need at least
connections. `NOMINATIM_API_POOL_SIZE` * `<number of configured workers>` connections.
For configuring the number of workers, refer to the section about
[Deploying the Python frontend](../admin/Deployment-Python.md).
#### NOMINATIM_QUERY_TIMEOUT #### NOMINATIM_QUERY_TIMEOUT
@@ -744,6 +746,6 @@ This settings enables
[SQL debugging](https://docs.sqlalchemy.org/en/20/core/engines.html#dbengine-logging) [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 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. query handling. It should only be used together with the CLI query functions.
Enabling it for server mode may have intended consequences. Use the `debug` Enabling it for server mode may have unintended consequences. Use the `debug`
parameter instead, which prints information on how the search is executed parameter instead, which prints information on how the search is executed
including SQL statements. including SQL statements.

4
docs/library/Configuration.md
View File

@@ -3,8 +3,8 @@
When using Nominatim through the library, it can be configured in exactly 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 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) created a [project directory](../admin/Import.md#creating-the-project-directory)
which contains all files belonging to the Noinatim instance. It can also contain which contains all files belonging to the Nominatim instance. It can also contain
an `.env` file with configuration options. Setting configuration paramters an `.env` file with configuration options. Setting configuration parameters
via environment variables works as well. via environment variables works as well.
Configuration options are resolved in the following order: Configuration options are resolved in the following order:

21
docs/library/Getting-Started.md
View File

@@ -3,8 +3,7 @@
The Nominatim search frontend can directly be used as a Python library in The Nominatim search frontend can directly be used as a Python library in
scripts and applications. When you have imported your own Nominatim database, 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 then it is no longer necessary to run a full web service for it and access
the database through http requests. With the Nominatim library it is possible the database through http requests. There are
to access all search functionality directly from your Python code. There are
also less constraints on the kinds of data that can be accessed. The library 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 allows to get access to more detailed information about the objects saved
in the database. in the database.
@@ -14,8 +13,8 @@ in the database.
be some smaller adjustments to the public interface until the next version. be some smaller adjustments to the public interface until the next version.
The library also misses a proper installation routine, so some manipulation The library also misses a proper installation routine, so some manipulation
of the PYTHONPATH is required. Use is only recommended for advanced Python of the PYTHONPATH is required. At the moment, use is only recommended for
programmers at the moment. developers wit some experience in Python.
## Installation ## Installation
@@ -55,7 +54,7 @@ This code snippet implements a simple search for the town if 'Brugge':
if not results: if not results:
print('Cannot find Brugge') print('Cannot find Brugge')
else: else:
print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}') print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
``` ```
=== "NominatimAPI" === "NominatimAPI"
@@ -71,7 +70,7 @@ This code snippet implements a simple search for the town if 'Brugge':
if not results: if not results:
print('Cannot find Brugge') print('Cannot find Brugge')
else: else:
print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}') print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}')
``` ```
The Nominatim library is designed around The Nominatim library is designed around
@@ -83,8 +82,8 @@ significantly.
For smaller scripts there is also a synchronous wrapper around the API. By For smaller scripts there is also a synchronous wrapper around the API. By
using `NominatimAPI`, you get exactly the same interface using classic functions. using `NominatimAPI`, you get exactly the same interface using classic functions.
The examples in this chapter will always show how work with both of the The examples in this chapter will always show-case both
implementations. The documentation itself will refer usually only to implementations. The documentation itself will usually refer only to
'Nominatim API class' when both flavours are meant. If a functionality is 'Nominatim API class' when both flavours are meant. If a functionality is
available only for the synchronous or asynchronous version, this will be available only for the synchronous or asynchronous version, this will be
explicitly mentioned. explicitly mentioned.
@@ -104,7 +103,7 @@ 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 Any configuration found in the `.env` file in this directory will automatically
used. used.
The second way to configure your Nominatim setup is through environment variables. Yo may also configure Nominatim be setting environment variables.
Normally, Nominatim will check the operating system environment. This can be Normally, Nominatim will check the operating system environment. This can be
overwritten by giving the constructor a dictionary of configuration parameters. overwritten by giving the constructor a dictionary of configuration parameters.
@@ -209,8 +208,8 @@ 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. 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 The library has a helper class `Locale` which helps extracting a name of a
place in the preferred language. It gets a list of language code in the place in the preferred language. It takes a single parameter with a list
order of preference. So of language codes in the order of preference. So
``` python ``` python
locale = napi.Locale(['fr', 'en']) locale = napi.Locale(['fr', 'en'])

4
docs/library/Input-Parameter-Types.md
View File

@@ -7,8 +7,8 @@ in the query functions of the API object.
The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and
[lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions [lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions
require references to places in the database. Below are listed the possible require references to places in the database. Below the possible
types for place identification. All types are dataclasses. types for place identification are listed. All types are dataclasses.
### PlaceID ### PlaceID

6
docs/library/Low-Level-DB-Access.md
View File

@@ -1,13 +1,13 @@
# Low-level connections # Low-level connections
The `NominatimAPIAsync` class allows to directly access the underlying The `NominatimAPIAsync` class allows to directly access the underlying
database connection to explore the data more directly. Nominatim uses database connection to explore the raw data. Nominatim uses
[SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please [SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please
refer to the documentation of the library to understand how to write SQL. 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 To get access to a search connection, use the `begin()` function of your
API object. The function returns a context manager. Use with a `with` API object. This returns a `SearchConnection` object described below
statement. This returns a `SearchConnection` object described below. Its wrapped in a context manager. Its
`t` property has definitions for all Nominatim search tables. For an `t` property has definitions for all Nominatim search tables. For an
overview of available tables, refer to the overview of available tables, refer to the
[Development Layout](../develop/Database-Layout.md) in in the development [Development Layout](../develop/Database-Layout.md) in in the development

14
docs/library/Result-Handling.md
View File

@@ -1,7 +1,7 @@
# Result handling # Result handling
The search functions of the Nominatim API always return a result object that The search functions of the Nominatim API always return a result object
contains the full raw information about the place that is available in the with the raw information about the place that is available in the
database. This section discusses data types used in the results and utility database. This section discusses data types used in the results and utility
functions that allow further processing of the results. functions that allow further processing of the results.
@@ -9,8 +9,8 @@ functions that allow further processing of the results.
### Sources ### Sources
Nominatim takes the result data from multiple souces. The `source_table` field Nominatim takes the result data from multiple sources. The `source_table` field
in the result describes, from which source the result was retrived. in the result describes, from which source the result was retrieved.
::: nominatim.api.SourceTable ::: nominatim.api.SourceTable
options: options:
@@ -21,15 +21,15 @@ in the result describes, from which source the result was retrived.
When the `address_details` parameter is set, then functions return not When the `address_details` parameter is set, then functions return not
only information about the result place but also about the place that only information about the result place but also about the place that
make up the address. This information is almost always required, when you 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. want to present the user with a human-readable description of the result.
See also [Localization](#localization) below. See also [Localization](#localization) below.
The address details are available in the `address_rows` field as a ordered 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 list of `AddressLine` objects with the country information last. The list also
contains the result place itself and some artificial entries, for example, contains the result place itself and some artificial entries, for example,
for the housenumber or the country code. This makes processing and creating for the house number or the country code. This makes processing and creating
a full address easiert. a full address easier.
::: nominatim.api.AddressLine ::: nominatim.api.AddressLine
options: options:

4
nominatim/api/types.py
View File

@@ -315,8 +315,8 @@ class DataLayer(enum.Flag):
for reverse and forward search. for reverse and forward search.
""" """
ADDRESS = enum.auto() ADDRESS = enum.auto()
""" The address layer contains all places that have a fully qualified """ The address layer contains all places relavant for addresses:
address that includes a house number (or a house name equivalent, 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 for some addresses) and places that can be part of an address like
roads, cities, states. roads, cities, states.
""" """

2
nominatim/tokenizer/base.py
View File

@@ -238,7 +238,7 @@ class AbstractTokenizer(ABC):
Arguments: Arguments:
conn: Open connection to the database which may be used to conn: Open connection to the database which may be used to
retrive the words. retrieve the words.
num: Maximum number of words to return. num: Maximum number of words to return.
""" """