Search.md - update XML and JSON example output

[nominatim.git] / docs / customize / Settings.md

diff --git a/docs/customize/Settings.md b/docs/customize/Settings.md
index 7eebebe89beadf946eafcaa2014985daa926f508..ebfa2421a12d79a7a7580afb504b073642c4844b 100644 (file)
--- a/docs/customize/Settings.md
+++ b/docs/customize/Settings.md
@@ -112,6 +112,9 @@ Points to the file with additional configuration for the tokenizer.
 See the [Tokenizer](../customize/Tokenizers.md) descriptions for details
 on the file format.
 
 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            |                                                     |
 #### NOMINATIM_MAX_WORD_FREQUENCY
 
 | Summary            |                                                     |


@@ -145,12 +148,35 @@ Setting this option to 'yes' means that Nominatim skips reindexing of contained
 objects when the area becomes too large.
 
 
 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            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Restrict search languages |
 #### NOMINATIM_LANGUAGES
 
 | Summary            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Restrict search languages |

-| **Format:**        | comma,separated list of language codes |
+| **Format:**        | string: comma-separated list of language codes |

 | **Default:**       | _empty_ |
 
 Normally Nominatim will include all language variants of name:XX
 | **Default:**       | _empty_ |
 
 Normally Nominatim will include all language variants of name:XX


@@ -186,7 +212,7 @@ will be used.
 | **Description:**   | Enable searching for Tiger house number data |
 | **Format:**        | boolean |
 | **Default:**       | no |
 | **Description:**   | Enable searching for Tiger house number data |
 | **Format:**        | boolean |
 | **Default:**       | no |

-| **After Changes:** | run `nominatim --refresh --functions` |
+| **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.
 
 When this setting is enabled, search and reverse queries also take data
 from [Tiger house number data](Tiger.md) into account.


@@ -199,7 +225,7 @@ from [Tiger house number data](Tiger.md) into account.
 | **Description:**   | Enable searching in external house number tables |
 | **Format:**        | boolean |
 | **Default:**       | no |
 | **Description:**   | Enable searching in external house number tables |
 | **Format:**        | boolean |
 | **Default:**       | no |

-| **After Changes:** | run `nominatim --refresh --functions` |
+| **After Changes:** | run `nominatim refresh --functions` |

 | **Comment:**       | Do not use. |
 
 When this setting is enabled, search queries also take data from external
 | **Comment:**       | Do not use. |
 
 When this setting is enabled, search queries also take data from external


@@ -283,7 +309,7 @@ setting to define the password for proxies that require a login.
 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
 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
+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.
 
 what you are doing. If the osm2pgsql version is not compatible, then the
 result is undefined.
 


@@ -300,31 +326,21 @@ 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.
 
 [wikipedia ranking file](../admin/Import.md#wikipediawikidata-rankings). When
 unset, Nominatim expects the data to be saved in the project directory.
 

-#### NOMINATIM_PHRASE_CONFIG
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Configuration file for special phrase imports |
-| **Format:**        | path |
-| **Default:**       | _empty_ (use default settings) |
-
-The _phrase_config_ file configures black and white lists of tag types,
-so that some of them can be ignored, when loading special phrases from
-the OSM wiki. The default settings can be found in the configuration
-directory as `phrase-settings.json`.
-

 #### NOMINATIM_ADDRESS_LEVEL_CONFIG
 
 | Summary            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Configuration file for rank assignments |
 | **Format:**        | path |
 #### NOMINATIM_ADDRESS_LEVEL_CONFIG
 
 | Summary            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Configuration file for rank assignments |
 | **Format:**        | path |

-| **Default:**       | _empty_ (use default settings) |
+| **Default:**       | address-levels.json |

 
 

-The _address level config_ configures rank assignments for places. See
+The _address level configuration_ defines the rank assignments for places. See

 [Place Ranking](Ranking.md) for a detailed explanation what rank assignments
 [Place Ranking](Ranking.md) for a detailed explanation what rank assignments

-are and what the configuration file must look like. The default configuration
-can be found in the configuration directory as `address-levels.json`.
+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
 
 
 #### NOMINATIM_IMPORT_STYLE
 


@@ -335,9 +351,13 @@ can be found in the configuration directory as `address-levels.json`.
 | **Default:**       | extratags |
 
 The _style configuration_ describes which OSM objects and tags are taken
 | **Default:**       | extratags |
 
 The _style configuration_ describes which OSM objects and tags are taken

-into consideration for the search database. This setting may either
-be a string pointing to one of the internal styles or it may be a path
-pointing to a custom style.
+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
 
 See [Import Styles](Import-Styles.md)
 for more information on the available internal styles and the format of the


@@ -357,6 +377,9 @@ 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.
 
 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
 !!! warning
 
     The flatnode file is not only used during the initial import but also


@@ -604,6 +627,23 @@ with a single query.
 
 Setting this parameter to 0 disables polygon output completely.
 
 
 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` |
+
+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.
+
+

 ### Logging Settings
 
 #### NOMINATIM_LOG_DB
 ### Logging Settings
 
 #### NOMINATIM_LOG_DB


@@ -634,12 +674,16 @@ Can be used as the same time as NOMINATIM_LOG_FILE.
 | **After Changes:** | run `nominatim refresh --website` |
 
 Enable logging of requests into a file with this setting by setting the log
 | **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. The entries in the log file have the following format:
+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> <execution time in s> <number of results> <type> "<query string>"
 
 Request time is the time when the request was started. The execution time is
 
     <request time> <execution time in s> <number of results> <type> "<query string>"
 
 Request time is the time when the request was started. The execution time is

-given in ms and corresponds to the time the query took executing in PHP.
+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.
 type contains the name of the endpoint used.
 
 Can be used as the same time as NOMINATIM_LOG_DB.