X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/751563644fe6572f7c63f67525ae56f4d9133e5c..3bb27fbee6acce772e008533b76174a35d34bee4:/docs/customize/Settings.md diff --git a/docs/customize/Settings.md b/docs/customize/Settings.md index 92afc8e0..ef0e1f21 100644 --- a/docs/customize/Settings.md +++ b/docs/customize/Settings.md @@ -9,7 +9,7 @@ variables: through an `.env` configuration file or through an environment variable. The `.env` configuration file needs to be placed into the -[project directory](../admin/Import/#creating-the-project-directory). It +[project directory](../admin/Import.md#creating-the-project-directory). It must contain configuration parameters in `=` format. Please refer to the dotenv documentation for details. @@ -23,5 +23,727 @@ download the next change, you can temporarily disable the update interval: If a configuration option is defined through .env file and environment variable, then the latter takes precedence. -# Configuration Parameter Reference +## Configuration Parameter Reference +### Import and Database Settings + +#### NOMINATIM_DATABASE_DSN + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Database connection string | +| **Format:** | string: `pgsql:=;=;...` | +| **Default:** | pgsql:dbname=nominatim | +| **After Changes:** | run `nominatim refresh --website` | + +Sets the connection parameters for the Nominatim database. At a minimum +the name of the database (`dbname`) is required. You can set any additional +parameter that is understood by libpq. See the [Postgres documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS) for a full list. + +!!! note + It is usually recommended not to set the password directly in this + configuration parameter. Use a + [password file](https://www.postgresql.org/docs/current/libpq-pgpass.html) + instead. + + +#### NOMINATIM_DATABASE_WEBUSER + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Database query user | +| **Format:** | string | +| **Default:** | www-data | +| **After Changes:** | cannot be changed after import | + +Defines the name of the database user that will run search queries. Usually +this is the user under which the webserver is executed. When running Nominatim +via php-fpm, you can also define a separate query user. The Postgres user +needs to be set up before starting the import. + +Nominatim grants minimal rights to this user to all tables that are needed +for running geocoding queries. + + +#### NOMINATIM_DATABASE_MODULE_PATH + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Directory where to find the PostgreSQL server module | +| **Format:** | path | +| **Default:** | _empty_ (use `/module`) | +| **After Changes:** | run `nominatim refresh --functions` | +| **Comment:** | Legacy tokenizer only | + +Defines the directory in which the PostgreSQL server module `nominatim.so` +is stored. The directory and module must be accessible by the PostgreSQL +server. + +For information on how to use this setting when working with external databases, +see [Advanced Installations](../admin/Advanced-Installations.md). + +The option is only used by the Legacy tokenizer and ignored otherwise. + + +#### NOMINATIM_TOKENIZER + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Tokenizer used for normalizing and parsing queries and names | +| **Format:** | string | +| **Default:** | icu | +| **After Changes:** | cannot be changed after import | + +Sets the tokenizer type to use for the import. For more information on +available tokenizers and how they are configured, see +[Tokenizers](../customize/Tokenizers.md). + + +#### NOMINATIM_TOKENIZER_CONFIG + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Configuration file for the tokenizer | +| **Format:** | path | +| **Default:** | _empty_ (default file depends on tokenizer) | +| **After Changes:** | see documentation for each tokenizer | + +Points to the file with additional configuration for the tokenizer. +See the [Tokenizer](../customize/Tokenizers.md) descriptions for details +on the file format. + +If a relative path is given, then the file is searched first relative to the +project directory and then in the global settings directory. + +#### NOMINATIM_MAX_WORD_FREQUENCY + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Number of occurrences before a word is considered frequent | +| **Format:** | int | +| **Default:** | 50000 | +| **After Changes:** | cannot be changed after import | +| **Comment:** | Legacy tokenizer only | + +The word frequency count is used by the Legacy tokenizer to automatically +identify _stop words_. Any partial term that occurs more often then what +is defined in this setting, is effectively ignored during search. + + +#### NOMINATIM_LIMIT_REINDEXING + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Avoid invalidating large areas | +| **Format:** | bool | +| **Default:** | yes | + +Nominatim computes the address of each place at indexing time. This has the +advantage to make search faster but also means that more objects needs to +be invalidated when the data changes. For example, changing the name of +the state of Florida would require recomputing every single address point +in the state to make the new name searchable in conjunction with addresses. + +Setting this option to 'yes' means that Nominatim skips reindexing of contained +objects when the area becomes too large. + + +#### NOMINATIM_LANGUAGES + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Restrict search languages | +| **Format:** | string: comma-separated list of language codes | +| **Default:** | _empty_ | + +Normally Nominatim will include all language variants of name:XX +in the search index. Set this to a comma separated list of language +codes, to restrict import to a subset of languages. + +Currently only affects the initial import of country names and special phrases. + + +#### NOMINATIM_TERM_NORMALIZATION + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Rules for normalizing terms for comparisons | +| **Format:** | string: semicolon-separated list of ICU rules | +| **Default:** | :: NFD (); [[:Nonspacing Mark:] [:Cf:]] >; :: lower (); [[:Punctuation:][:Space:]]+ > ' '; :: NFC (); | +| **Comment:** | Legacy tokenizer only | + +[Special phrases](Special-Phrases.md) have stricter matching requirements than +normal search terms. They must appear exactly in the query after this term +normalization has been applied. + +Only has an effect on the Legacy tokenizer. For the ICU tokenizer the rules +defined in the +[normalization section](Tokenizers.md#normalization-and-transliteration) +will be used. + + +#### NOMINATIM_USE_US_TIGER_DATA + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Enable searching for Tiger house number data | +| **Format:** | boolean | +| **Default:** | no | +| **After Changes:** | run `nominatim refresh --functions` | + +When this setting is enabled, search and reverse queries also take data +from [Tiger house number data](Tiger.md) into account. + + +#### NOMINATIM_USE_AUX_LOCATION_DATA + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Enable searching in external house number tables | +| **Format:** | boolean | +| **Default:** | no | +| **After Changes:** | run `nominatim refresh --functions` | +| **Comment:** | Do not use. | + +When this setting is enabled, search queries also take data from external +house number tables into account. + +*Warning:* This feature is currently unmaintained and should not be used. + + +#### NOMINATIM_HTTP_PROXY + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Use HTTP proxy when downloading data | +| **Format:** | boolean | +| **Default:** | no | + +When this setting is enabled and at least +[NOMINATIM_HTTP_PROXY_HOST](#nominatim_http_proxy_host) and +[NOMINATIM_HTTP_PROXY_PORT](#nominatim_http_proxy_port) are set, the +configured proxy will be used, when downloading external data like +replication diffs. + + +#### NOMINATIM_HTTP_PROXY_HOST + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Host name of the proxy to use | +| **Format:** | string | +| **Default:** | _empty_ | + +When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, this setting +configures the proxy host name. + + +#### NOMINATIM_HTTP_PROXY_PORT + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Port number of the proxy to use | +| **Format:** | integer | +| **Default:** | 3128 | + +When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, this setting +configures the port number to use with the proxy. + + +#### NOMINATIM_HTTP_PROXY_LOGIN + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Username for proxies that require login | +| **Format:** | string | +| **Default:** | _empty_ | + +When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, use this +setting to define the username for proxies that require a login. + + +#### NOMINATIM_HTTP_PROXY_PASSWORD + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Password for proxies that require login | +| **Format:** | string | +| **Default:** | _empty_ | + +When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, use this +setting to define the password for proxies that require a login. + + +#### NOMINATIM_OSM2PGSQL_BINARY + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Location of the osm2pgsql binary | +| **Format:** | path | +| **Default:** | _empty_ (use binary shipped with Nominatim) | +| **Comment:** | EXPERT ONLY | + +Nominatim uses [osm2pgsql](https://osm2pgsql.org) to load the OSM data +initially into the database. Nominatim comes bundled with a version of +osm2pgsql that is guaranteed to be compatible. Use this setting to use +a different binary instead. You should do this only when you know exactly +what you are doing. If the osm2pgsql version is not compatible, then the +result is undefined. + + +#### NOMINATIM_WIKIPEDIA_DATA_PATH + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Directory with the wikipedia importance data | +| **Format:** | path | +| **Default:** | _empty_ (project directory) | + +Set a custom location for the +[wikipedia ranking file](../admin/Import.md#wikipediawikidata-rankings). When +unset, Nominatim expects the data to be saved in the project directory. + +#### NOMINATIM_ADDRESS_LEVEL_CONFIG + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Configuration file for rank assignments | +| **Format:** | path | +| **Default:** | address-levels.json | + +The _address level configuration_ defines the rank assignments for places. See +[Place Ranking](Ranking.md) for a detailed explanation what rank assignments +are and what the configuration file must look like. + +When a relative path is given, then the file is searched first relative to the +project directory and then in the global settings directory. + + +#### NOMINATIM_IMPORT_STYLE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Configuration to use for the initial OSM data import | +| **Format:** | string or path | +| **Default:** | extratags | + +The _style configuration_ describes which OSM objects and tags are taken +into consideration for the search database. Nominatim comes with a set +of pre-configured styles, that may be configured here. + +You can also write your own custom style and point the setting to the file +with the style. When a relative path is given, then the style file is searched +first relative to the project directory and then in the global settings +directory. + +See [Import Styles](Import-Styles.md) +for more information on the available internal styles and the format of the +configuration file. + +#### NOMINATIM_FLATNODE_FILE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Location of osm2pgsql flatnode file | +| **Format:** | path | +| **Default:** | _empty_ (do not use a flatnote file) | +| **After Changes:** | Only change when moving the file physically. | + +The `osm2pgsql flatnode file` is file that efficiently stores geographic +location for OSM nodes. For larger imports it can significantly speed up +the import. When this option is unset, then osm2pgsql uses a PsotgreSQL table +to store the locations. + +When a relative path is given, then the flatnode file is created/searched +relative to the project directory. + +!!! warning + + The flatnode file is not only used during the initial import but also + when adding new data with `nominatim add-data` or `nominatim replication`. + Make sure you keep the flatnode file around and this setting unmodified, + if you plan to add more data or run regular updates. + + +#### NOMINATIM_TABLESPACE_* + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Group of settings for distributing the database over tablespaces | +| **Format:** | string | +| **Default:** | _empty_ (do not use a table space) | +| **After Changes:** | no effect after initial import | + +Nominatim allows to distribute the search database over up to 10 different +[PostgreSQL tablespaces](https://www.postgresql.org/docs/current/manage-ag-tablespaces.html). +If you use this option, make sure that the tablespaces exist before starting +the import. + +The available tablespace groups are: + +NOMINATIM_TABLESPACE_SEARCH_DATA +: Data used by the geocoding frontend. + +NOMINATIM_TABLESPACE_SEARCH_INDEX +: Indexes used by the geocoding frontend. + +NOMINATIM_TABLESPACE_OSM_DATA +: Raw OSM data cache used for import and updates. + +NOMINATIM_TABLESPACE_OSM_DATA +: Indexes on the raw OSM data cache. + +NOMINATIM_TABLESPACE_PLACE_DATA +: Data table with the pre-filtered but still unprocessed OSM data. + Used only during imports and updates. + +NOMINATIM_TABLESPACE_PLACE_INDEX +: Indexes on raw data table. Used only during imports and updates. + +NOMINATIM_TABLESPACE_ADDRESS_DATA +: Data tables used for computing search terms and addresses of places + during import and updates. + +NOMINATIM_TABLESPACE_ADDRESS_INDEX +: Indexes on the data tables for search term and address computation. + Used only for import and updates. + +NOMINATIM_TABLESPACE_AUX_DATA +: Auxiliary data tables for non-OSM data, e.g. for Tiger house number data. + +NOMINATIM_TABLESPACE_AUX_INDEX +: Indexes on auxiliary data tables. + + +### Replication Update Settings + +#### NOMINATIM_REPLICATION_URL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Base URL of the replication service | +| **Format:** | url | +| **Default:** | https://planet.openstreetmap.org/replication/minute | +| **After Changes:** | run `nominatim replication --init` | + +Replication services deliver updates to OSM data. Use this setting to choose +which replication service to use. See [Updates](../admin/Update.md) for more +information on how to set up regular updates. + +#### NOMINATIM_REPLICATION_MAX_DIFF + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Maximum amount of data to download per update cycle (in MB) | +| **Format:** | integer | +| **Default:** | 50 | +| **After Changes:** | restart the replication process | + +At each update cycle Nominatim downloads diffs until either no more diffs +are available on the server (i.e. the database is up-to-date) or the limit +given in this setting is exceeded. Nominatim guarantees to downloads at least +one diff, if one is available, no matter how small the setting. + +The default for this setting is fairly conservative because Nominatim keeps +all data downloaded in one cycle in RAM. Using large values in a production +server may interfere badly with the search frontend because it evicts data +from RAM that is needed for speedy answers to incoming requests. It is usually +a better idea to keep this setting lower and run multiple update cycles +to catch up with updates. + +When catching up in non-production mode, for example after the initial import, +the setting can easily be changed temporarily on the command line: + + NOMINATIM_REPLICATION_MAX_DIFF=3000 nominatim replication + + +#### NOMINATIM_REPLICATION_UPDATE_INTERVAL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Publication interval of the replication service (in seconds) | +| **Format:** | integer | +| **Default:** | 75 | +| **After Changes:** | restart the replication process | + +This setting determines when Nominatim will attempt to download again a new +update. The time is computed from the publication date of the last diff +downloaded. Setting this to a slightly higher value than the actual +publication interval avoids unnecessary rechecks. + + +#### NOMINATIM_REPLICATION_RECHECK_INTERVAL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Wait time to recheck for a pending update (in seconds) | +| **Format:** | integer | +| **Default:** | 60 | +| **After Changes:** | restart the replication process | + +When replication updates are run in continuous mode (using `nominatim replication`), +this setting determines how long Nominatim waits until it looks for updates +again when updates were not available on the server. + +Note that this is different from +[NOMINATIM_REPLICATION_UPDATE_INTERVAL](#nominatim_replication_update_interval). +Nominatim will never attempt to query for new updates for UPDATE_INTERVAL +seconds after the current database date. Only after the update interval has +passed it asks for new data. If then no new data is found, it waits for +RECHECK_INTERVAL seconds before it attempts again. + +### API Settings + +#### NOMINATIM_CORS_NOACCESSCONTROL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Send permissive CORS access headers | +| **Format:** | boolean | +| **Default:** | yes | +| **After Changes:** | run `nominatim refresh --website` | + +When this setting is enabled, API HTTP responses include the HTTP +[CORS](https://en.wikipedia.org/wiki/CORS) headers +`access-control-allow-origin: *` and `access-control-allow-methods: OPTIONS,GET`. + +#### NOMINATIM_MAPICON_URL + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | URL prefix for static icon images | +| **Format:** | url | +| **Default:** | _empty_ | +| **After Changes:** | run `nominatim refresh --website` | + +When a mapicon URL is configured, then Nominatim includes an additional `icon` +field in the responses, pointing to an appropriate icon for the place type. + +Map icons used to be included in Nominatim itself but now have moved to the +[nominatim-ui](https://github.com/osm-search/nominatim-ui/) project. If you +want the URL to be included in API responses, make the `/mapicon` +directory of the project available under a public URL and point this setting +to the directory. + + +#### NOMINATIM_DEFAULT_LANGUAGE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Language of responses when no language is requested | +| **Format:** | language code | +| **Default:** | _empty_ (use the local language of the feature) | +| **After Changes:** | run `nominatim refresh --website` | + +Nominatim localizes the place names in responses when the corresponding +translation is available. Users can request a custom language setting through +the HTTP accept-languages header or through the explicit parameter +[accept-languages](../api/Search.md#language-of-results). If neither is +given, it falls back to this setting. If the setting is also empty, then +the local languages (in OSM: the name tag without any language suffix) is +used. + + +#### NOMINATIM_SEARCH_BATCH_MODE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Enable a special batch query mode | +| **Format:** | boolean | +| **Default:** | no | +| **After Changes:** | run `nominatim refresh --website` | +| **Comment:** | PHP frontend only | + + +This feature is currently undocumented and potentially broken. + + +#### NOMINATIM_SEARCH_NAME_ONLY_THRESHOLD + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Threshold for switching the search index lookup strategy | +| **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 +for place lookups. Otherwise the name and any address information is used. + +This setting only has an effect after `nominatim refresh --word-counts` has +been called to compute the word frequencies. + + +#### NOMINATIM_LOOKUP_MAX_COUNT + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Maximum number of OSM ids accepted by /lookup | +| **Format:** | integer | +| **Default:** | 50 | +| **After Changes:** | run `nominatim refresh --website` | + +The /lookup point accepts list of ids to look up address details for. This +setting restricts the number of places a user may look up with a single +request. + + +#### NOMINATIM_POLYGON_OUTPUT_MAX_TYPES + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Number of different geometry formats that may be returned | +| **Format:** | integer | +| **Default:** | 1 | +| **After Changes:** | run `nominatim refresh --website` | + +Nominatim supports returning full geometries of places. The geometries may +be requested in different formats with one of the +[`polygon_*` parameters](../api/Search.md#polygon-output). Use this +setting to restrict the number of geometry types that may be requested +with a single query. + +Setting this parameter to 0 disables polygon output completely. + + +#### NOMINATIM_SEARCH_WITHIN_COUNTRIES + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Disable search for elements that are not in the country grid | +| **Format:** | boolean | +| **Default:** | no | +| **After Changes:** | run `nominatim refresh --website` | +| **Comment:** | PHP frontend only | + +Enable to search elements just within countries. + +When enabled, if, despite not finding a point within the static grid of countries, it +finds a geometry of a region, do not return the geometry. +Return "Unable to geocode" instead. + + +#### NOMINATIM_SERVE_LEGACY_URLS + +| 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 ` * ` +connections. + +#### 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 + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Log requests into the database | +| **Format:** | boolean | +| **Default:** | no | +| **After Changes:** | run `nominatim refresh --website` | + +Enable logging requests into a database table with this setting. The logs +can be found in the table `new_query_log`. + +When using this logging method, it is advisable to set up a job that +regularly clears out old logging information. Nominatim will not do that +on its own. + +Can be used as the same time as NOMINATIM_LOG_FILE. + +#### NOMINATIM_LOG_FILE + +| Summary | | +| -------------- | --------------------------------------------------- | +| **Description:** | Log requests into a file | +| **Format:** | path | +| **Default:** | _empty_ (logging disabled) | +| **After Changes:** | run `nominatim refresh --website` | + +Enable logging of requests into a file with this setting by setting the log +file where to log to. A relative file name is assumed to be relative to +the project directory. + + +The entries in the log file have the following format: + + "" + +Request time is the time when the request was started. The execution time is +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 intended consequences. Use the `debug` +parameter instead, which prints information on how the search is executed +including SQL statements.