docs/customize/Settings.md

   1 This section provides a reference of all configuration parameters that can
   2 be used with Nominatim.
   3
   4 # Configuring Nominatim
   5
   6 Nominatim uses [dotenv](https://github.com/theskumar/python-dotenv) to manage
   7 its configuration settings. There are two means to set configuration
   8 variables: through an `.env` configuration file or through an environment
   9 variable.
  10
  11 The `.env` configuration file needs to be placed into the
  12 [project directory](../admin/Import.md#creating-the-project-directory). It
  13 must contain configuration parameters in `<parameter>=<value>` format.
  14 Please refer to the dotenv documentation for details.
  15
  16 The configuration options may also be set in the form of shell environment
  17 variables. This is particularly useful, when you want to temporarily change
  18 a configuration option. For example, to force the replication serve to
  19 download the next change, you can temporarily disable the update interval:
  20
  21     NOMINATIM_REPLICATION_UPDATE_INTERVAL=0 nominatim replication --once
  22
  23 If a configuration option is defined through .env file and environment
  24 variable, then the latter takes precedence.
  25
  26 ## Configuration Parameter Reference
  27
  28 ### Import and Database Settings
  29
  30 #### NOMINATIM_DATABASE_DSN
  31
  32 | Summary            |                                                     |
  33 | --------------     | --------------------------------------------------- |
  34 | **Description:**   | Database connection string |
  35 | **Format:**        | string: `pgsql:<param1>=<value1>;<param2>=<value2>;...` |
  36 | **Default:**       | pgsql:dbname=nominatim |
  37 | **After Changes:** | run `nominatim refresh --website` |
  38
  39 Sets the connection parameters for the Nominatim database. At a minimum
  40 the name of the database (`dbname`) is required. You can set any additional
  41 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.
  42
  43 !!! note
  44     It is usually recommended not to set the password directly in this
  45     configuration parameter. Use a
  46     [password file](https://www.postgresql.org/docs/current/libpq-pgpass.html)
  47     instead.
  48
  49
  50 #### NOMINATIM_DATABASE_WEBUSER
  51
  52 | Summary            |                                                     |
  53 | --------------     | --------------------------------------------------- |
  54 | **Description:**   | Database query user |
  55 | **Format:**        | string  |
  56 | **Default:**       | www-data |
  57 | **After Changes:** | cannot be changed after import |
  58
  59 Defines the name of the database user that will run search queries. Usually
  60 this is the user under which the webserver is executed. The Postgres user
  61 needs to be set up before starting the import.
  62
  63 Nominatim grants minimal rights to this user to all tables that are needed
  64 for running geocoding queries.
  65
  66
  67 #### NOMINATIM_TOKENIZER
  68
  69 | Summary            |                                                     |
  70 | --------------     | --------------------------------------------------- |
  71 | **Description:**   | Tokenizer used for normalizing and parsing queries and names |
  72 | **Format:**        | string |
  73 | **Default:**       | icu |
  74 | **After Changes:** | cannot be changed after import |
  75
  76 Sets the tokenizer type to use for the import. For more information on
  77 available tokenizers and how they are configured, see
  78 [Tokenizers](../customize/Tokenizers.md).
  79
  80
  81 #### NOMINATIM_TOKENIZER_CONFIG
  82
  83 | Summary            |                                                     |
  84 | --------------     | --------------------------------------------------- |
  85 | **Description:**   | Configuration file for the tokenizer |
  86 | **Format:**        | path |
  87 | **Default:**       | _empty_ (default file depends on tokenizer) |
  88 | **After Changes:** | see documentation for each tokenizer |
  89
  90 Points to the file with additional configuration for the tokenizer.
  91 See the [Tokenizer](../customize/Tokenizers.md) descriptions for details
  92 on the file format.
  93
  94 If a relative path is given, then the file is searched first relative to the
  95 project directory and then in the global settings directory.
  96
  97
  98 #### NOMINATIM_LIMIT_REINDEXING
  99
 100 | Summary            |                                                     |
 101 | --------------     | --------------------------------------------------- |
 102 | **Description:**   | Avoid invalidating large areas |
 103 | **Format:**        | bool |
 104 | **Default:**       | yes |
 105
 106 Nominatim computes the address of each place at indexing time. This has the
 107 advantage to make search faster but also means that more objects needs to
 108 be invalidated when the data changes. For example, changing the name of
 109 the state of Florida would require recomputing every single address point
 110 in the state to make the new name searchable in conjunction with addresses.
 111
 112 Setting this option to 'yes' means that Nominatim skips reindexing of contained
 113 objects when the area becomes too large.
 114
 115
 116 #### NOMINATIM_LANGUAGES
 117
 118 | Summary            |                                                     |
 119 | --------------     | --------------------------------------------------- |
 120 | **Description:**   | Restrict search languages |
 121 | **Format:**        | string: comma-separated list of language codes |
 122 | **Default:**       | _empty_ |
 123
 124 Normally Nominatim will include all language variants of name:XX
 125 in the search index. Set this to a comma separated list of language
 126 codes, to restrict import to a subset of languages.
 127
 128 Currently only affects the initial import of country names and special phrases.
 129
 130
 131 #### NOMINATIM_USE_US_TIGER_DATA
 132
 133 | Summary            |                                                     |
 134 | --------------     | --------------------------------------------------- |
 135 | **Description:**   | Enable searching for Tiger house number data |
 136 | **Format:**        | boolean |
 137 | **Default:**       | no |
 138 | **After Changes:** | run `nominatim refresh --functions` |
 139
 140 When this setting is enabled, search and reverse queries also take data
 141 from [Tiger house number data](Tiger.md) into account.
 142
 143
 144 #### NOMINATIM_USE_AUX_LOCATION_DATA
 145
 146 | Summary            |                                                     |
 147 | --------------     | --------------------------------------------------- |
 148 | **Description:**   | Enable searching in external house number tables |
 149 | **Format:**        | boolean |
 150 | **Default:**       | no |
 151 | **After Changes:** | run `nominatim refresh --functions` |
 152 | **Comment:**       | Do not use. |
 153
 154 When this setting is enabled, search queries also take data from external
 155 house number tables into account.
 156
 157 *Warning:* This feature is currently unmaintained and should not be used.
 158
 159
 160 #### NOMINATIM_HTTP_PROXY
 161
 162 | Summary            |                                                     |
 163 | --------------     | --------------------------------------------------- |
 164 | **Description:**   | Use HTTP proxy when downloading data |
 165 | **Format:**        | boolean |
 166 | **Default:**       | no |
 167
 168 When this setting is enabled and at least
 169 [NOMINATIM_HTTP_PROXY_HOST](#nominatim_http_proxy_host) and
 170 [NOMINATIM_HTTP_PROXY_PORT](#nominatim_http_proxy_port) are set, the
 171 configured proxy will be used, when downloading external data like
 172 replication diffs.
 173
 174
 175 #### NOMINATIM_HTTP_PROXY_HOST
 176
 177 | Summary            |                                                     |
 178 | --------------     | --------------------------------------------------- |
 179 | **Description:**   | Host name of the proxy to use |
 180 | **Format:**        | string |
 181 | **Default:**       | _empty_ |
 182
 183 When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, this setting
 184 configures the proxy host name.
 185
 186
 187 #### NOMINATIM_HTTP_PROXY_PORT
 188
 189 | Summary            |                                                     |
 190 | --------------     | --------------------------------------------------- |
 191 | **Description:**   | Port number of the proxy to use |
 192 | **Format:**        | integer |
 193 | **Default:**       | 3128 |
 194
 195 When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, this setting
 196 configures the port number to use with the proxy.
 197
 198
 199 #### NOMINATIM_HTTP_PROXY_LOGIN
 200
 201 | Summary            |                                                     |
 202 | --------------     | --------------------------------------------------- |
 203 | **Description:**   | Username for proxies that require login |
 204 | **Format:**        | string |
 205 | **Default:**       | _empty_ |
 206
 207 When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, use this
 208 setting to define the username for proxies that require a login.
 209
 210
 211 #### NOMINATIM_HTTP_PROXY_PASSWORD
 212
 213 | Summary            |                                                     |
 214 | --------------     | --------------------------------------------------- |
 215 | **Description:**   | Password for proxies that require login |
 216 | **Format:**        | string |
 217 | **Default:**       | _empty_ |
 218
 219 When [NOMINATIM_HTTP_PROXY](#nominatim_http_proxy) is enabled, use this
 220 setting to define the password for proxies that require a login.
 221
 222
 223 #### NOMINATIM_OSM2PGSQL_BINARY
 224
 225 | Summary            |                                                     |
 226 | --------------     | --------------------------------------------------- |
 227 | **Description:**   | Location of the osm2pgsql binary |
 228 | **Format:**        | path |
 229 | **Default:**       | _empty_ (use binary shipped with Nominatim) |
 230 | **Comment:**       | EXPERT ONLY |
 231
 232 Nominatim uses [osm2pgsql](https://osm2pgsql.org) to load the OSM data
 233 initially into the database. Nominatim comes bundled with a version of
 234 osm2pgsql that is guaranteed to be compatible. Use this setting to use
 235 a different binary instead. You should do this only when you know exactly
 236 what you are doing. If the osm2pgsql version is not compatible, then the
 237 result is undefined.
 238
 239
 240 #### NOMINATIM_WIKIPEDIA_DATA_PATH
 241
 242 | Summary            |                                                     |
 243 | --------------     | --------------------------------------------------- |
 244 | **Description:**   | Directory with the wikipedia importance data |
 245 | **Format:**        | path |
 246 | **Default:**       | _empty_ (project directory) |
 247
 248 Set a custom location for the
 249 [wikipedia ranking file](../admin/Import.md#wikipediawikidata-rankings). When
 250 unset, Nominatim expects the data to be saved in the project directory.
 251
 252 #### NOMINATIM_ADDRESS_LEVEL_CONFIG
 253
 254 | Summary            |                                                     |
 255 | --------------     | --------------------------------------------------- |
 256 | **Description:**   | Configuration file for rank assignments |
 257 | **Format:**        | path |
 258 | **Default:**       | address-levels.json |
 259
 260 The _address level configuration_ defines the rank assignments for places. See
 261 [Place Ranking](Ranking.md) for a detailed explanation what rank assignments
 262 are and what the configuration file must look like.
 263
 264 When a relative path is given, then the file is searched first relative to the
 265 project directory and then in the global settings directory.
 266
 267
 268 #### NOMINATIM_IMPORT_STYLE
 269
 270 | Summary            |                                                     |
 271 | --------------     | --------------------------------------------------- |
 272 | **Description:**   | Configuration to use for the initial OSM data import |
 273 | **Format:**        | string or path |
 274 | **Default:**       | extratags |
 275
 276 The _style configuration_ describes which OSM objects and tags are taken
 277 into consideration for the search database. Nominatim comes with a set
 278 of pre-configured styles, that may be configured here.
 279
 280 You can also write your own custom style and point the setting to the file
 281 with the style. When a relative path is given, then the style file is searched
 282 first relative to the project directory and then in the global settings
 283 directory.
 284
 285 See [Import Styles](Import-Styles.md)
 286 for more information on the available internal styles and the format of the
 287 configuration file.
 288
 289 #### NOMINATIM_FLATNODE_FILE
 290
 291 | Summary            |                                                     |
 292 | --------------     | --------------------------------------------------- |
 293 | **Description:**   | Location of osm2pgsql flatnode file |
 294 | **Format:**        | path |
 295 | **Default:**       | _empty_ (do not use a flatnote file) |
 296 | **After Changes:** | Only change when moving the file physically. |
 297
 298 The `osm2pgsql flatnode file` is file that efficiently stores geographic
 299 location for OSM nodes. For larger imports it can significantly speed up
 300 the import. When this option is unset, then osm2pgsql uses a PsotgreSQL table
 301 to store the locations.
 302
 303 When a relative path is given, then the flatnode file is created/searched
 304 relative to the project directory.
 305
 306 !!! warning
 307
 308     The flatnode file is not only used during the initial import but also
 309     when adding new data with `nominatim add-data` or `nominatim replication`.
 310     Make sure you keep the flatnode file around and this setting unmodified,
 311     if you plan to add more data or run regular updates.
 312
 313
 314 #### NOMINATIM_TABLESPACE_*
 315
 316 | Summary            |                                                     |
 317 | --------------     | --------------------------------------------------- |
 318 | **Description:**   | Group of settings for distributing the database over tablespaces |
 319 | **Format:**        | string |
 320 | **Default:**       | _empty_ (do not use a table space) |
 321 | **After Changes:** | no effect after initial import |
 322
 323 Nominatim allows to distribute the search database over up to 10 different
 324 [PostgreSQL tablespaces](https://www.postgresql.org/docs/current/manage-ag-tablespaces.html).
 325 If you use this option, make sure that the tablespaces exist before starting
 326 the import.
 327
 328 The available tablespace groups are:
 329
 330 NOMINATIM_TABLESPACE_SEARCH_DATA
 331 :    Data used by the geocoding frontend.
 332
 333 NOMINATIM_TABLESPACE_SEARCH_INDEX
 334 :    Indexes used by the geocoding frontend.
 335
 336 NOMINATIM_TABLESPACE_OSM_DATA
 337 :    Raw OSM data cache used for import and updates.
 338
 339 NOMINATIM_TABLESPACE_OSM_INDEX
 340 :    Indexes on the raw OSM data cache.
 341
 342 NOMINATIM_TABLESPACE_PLACE_DATA
 343 :    Data table with the pre-filtered but still unprocessed OSM data.
 344      Used only during imports and updates.
 345
 346 NOMINATIM_TABLESPACE_PLACE_INDEX
 347 :    Indexes on raw data table. Used only during imports and updates.
 348
 349 NOMINATIM_TABLESPACE_ADDRESS_DATA
 350 :    Data tables used for computing search terms and addresses of places
 351      during import and updates.
 352
 353 NOMINATIM_TABLESPACE_ADDRESS_INDEX
 354 :    Indexes on the data tables for search term and address computation.
 355      Used only for import and updates.
 356
 357 NOMINATIM_TABLESPACE_AUX_DATA
 358 :    Auxiliary data tables for non-OSM data, e.g. for Tiger house number data.
 359
 360 NOMINATIM_TABLESPACE_AUX_INDEX
 361 :    Indexes on auxiliary data tables.
 362
 363
 364 ### Replication Update Settings
 365
 366 #### NOMINATIM_REPLICATION_URL
 367
 368 | Summary            |                                                     |
 369 | --------------     | --------------------------------------------------- |
 370 | **Description:**   | Base URL of the replication service |
 371 | **Format:**        | url |
 372 | **Default:**       | https://planet.openstreetmap.org/replication/minute |
 373 | **After Changes:** | run `nominatim replication --init` |
 374
 375 Replication services deliver updates to OSM data. Use this setting to choose
 376 which replication service to use. See [Updates](../admin/Update.md) for more
 377 information on how to set up regular updates.
 378
 379 #### NOMINATIM_REPLICATION_MAX_DIFF
 380
 381 | Summary            |                                                     |
 382 | --------------     | --------------------------------------------------- |
 383 | **Description:**   | Maximum amount of data to download per update cycle (in MB) |
 384 | **Format:**        | integer |
 385 | **Default:**       | 50 |
 386 | **After Changes:** | restart the replication process |
 387
 388 At each update cycle Nominatim downloads diffs until either no more diffs
 389 are available on the server (i.e. the database is up-to-date) or the limit
 390 given in this setting is exceeded. Nominatim guarantees to downloads at least
 391 one diff, if one is available, no matter how small the setting.
 392
 393 The default for this setting is fairly conservative because Nominatim keeps
 394 all data downloaded in one cycle in RAM. Using large values in a production
 395 server may interfere badly with the search frontend because it evicts data
 396 from RAM that is needed for speedy answers to incoming requests. It is usually
 397 a better idea to keep this setting lower and run multiple update cycles
 398 to catch up with updates.
 399
 400 When catching up in non-production mode, for example after the initial import,
 401 the setting can easily be changed temporarily on the command line:
 402
 403     NOMINATIM_REPLICATION_MAX_DIFF=3000 nominatim replication
 404
 405
 406 #### NOMINATIM_REPLICATION_UPDATE_INTERVAL
 407
 408 | Summary            |                                                     |
 409 | --------------     | --------------------------------------------------- |
 410 | **Description:**   | Publication interval of the replication service (in seconds) |
 411 | **Format:**        | integer |
 412 | **Default:**       | 75 |
 413 | **After Changes:** | restart the replication process |
 414
 415 This setting determines when Nominatim will attempt to download again a new
 416 update. The time is computed from the publication date of the last diff
 417 downloaded. Setting this to a slightly higher value than the actual
 418 publication interval avoids unnecessary rechecks.
 419
 420
 421 #### NOMINATIM_REPLICATION_RECHECK_INTERVAL
 422
 423 | Summary            |                                                     |
 424 | --------------     | --------------------------------------------------- |
 425 | **Description:**   | Wait time to recheck for a pending update (in seconds)  |
 426 | **Format:**        | integer |
 427 | **Default:**       | 60 |
 428 | **After Changes:** | restart the replication process |
 429
 430 When replication updates are run in continuous mode (using `nominatim replication`),
 431 this setting determines how long Nominatim waits until it looks for updates
 432 again when updates were not available on the server.
 433
 434 Note that this is different from
 435 [NOMINATIM_REPLICATION_UPDATE_INTERVAL](#nominatim_replication_update_interval).
 436 Nominatim will never attempt to query for new updates for UPDATE_INTERVAL
 437 seconds after the current database date. Only after the update interval has
 438 passed it asks for new data. If then no new data is found, it waits for
 439 RECHECK_INTERVAL seconds before it attempts again.
 440
 441 ### API Settings
 442
 443 #### NOMINATIM_CORS_NOACCESSCONTROL
 444
 445 | Summary            |                                                     |
 446 | --------------     | --------------------------------------------------- |
 447 | **Description:**   | Send permissive CORS access headers |
 448 | **Format:**        | boolean |
 449 | **Default:**       | yes |
 450 | **After Changes:** | run `nominatim refresh --website` |
 451
 452 When this setting is enabled, API HTTP responses include the HTTP
 453 [CORS](https://en.wikipedia.org/wiki/CORS) headers
 454 `access-control-allow-origin: *` and `access-control-allow-methods: OPTIONS,GET`.
 455
 456 #### NOMINATIM_MAPICON_URL
 457
 458 | Summary            |                                                     |
 459 | --------------     | --------------------------------------------------- |
 460 | **Description:**   | URL prefix for static icon images |
 461 | **Format:**        | url |
 462 | **Default:**       | _empty_ |
 463 | **After Changes:** | run `nominatim refresh --website` |
 464
 465 When a mapicon URL is configured, then Nominatim includes an additional `icon`
 466 field in the responses, pointing to an appropriate icon for the place type.
 467
 468 Map icons used to be included in Nominatim itself but now have moved to the
 469 [nominatim-ui](https://github.com/osm-search/nominatim-ui/) project. If you
 470 want the URL to be included in API responses, make the `/mapicon`
 471 directory of the project available under a public URL and point this setting
 472 to the directory.
 473
 474
 475 #### NOMINATIM_DEFAULT_LANGUAGE
 476
 477 | Summary            |                                                     |
 478 | --------------     | --------------------------------------------------- |
 479 | **Description:**   | Language of responses when no language is requested |
 480 | **Format:**        | language code |
 481 | **Default:**       | _empty_ (use the local language of the feature) |
 482 | **After Changes:** | run `nominatim refresh --website` |
 483
 484 Nominatim localizes the place names in responses when the corresponding
 485 translation is available. Users can request a custom language setting through
 486 the HTTP accept-languages header or through the explicit parameter
 487 [accept-languages](../api/Search.md#language-of-results). If neither is
 488 given, it falls back to this setting. If the setting is also empty, then
 489 the local languages (in OSM: the name tag without any language suffix) is
 490 used.
 491
 492
 493 #### NOMINATIM_LOOKUP_MAX_COUNT
 494
 495 | Summary            |                                                     |
 496 | --------------     | --------------------------------------------------- |
 497 | **Description:**   | Maximum number of OSM ids accepted by /lookup |
 498 | **Format:**        | integer |
 499 | **Default:**       | 50 |
 500 | **After Changes:** | run `nominatim refresh --website` |
 501
 502 The /lookup point accepts list of ids to look up address details for. This
 503 setting restricts the number of places a user may look up with a single
 504 request.
 505
 506
 507 #### NOMINATIM_POLYGON_OUTPUT_MAX_TYPES
 508
 509 | Summary            |                                                     |
 510 | --------------     | --------------------------------------------------- |
 511 | **Description:**   | Number of different geometry formats that may be returned |
 512 | **Format:**        | integer |
 513 | **Default:**       | 1 |
 514 | **After Changes:** | run `nominatim refresh --website` |
 515
 516 Nominatim supports returning full geometries of places. The geometries may
 517 be requested in different formats with one of the
 518 [`polygon_*` parameters](../api/Search.md#polygon-output). Use this
 519 setting to restrict the number of geometry types that may be requested
 520 with a single query.
 521
 522 Setting this parameter to 0 disables polygon output completely.
 523
 524
 525 #### NOMINATIM_SEARCH_WITHIN_COUNTRIES
 526
 527 | Summary            |                                                     |
 528 | --------------     | --------------------------------------------------- |
 529 | **Description:**   | Disable search for elements that are not in the country grid |
 530 | **Format:**        | boolean |
 531 | **Default:**       | no |
 532 | **After Changes:** | run `nominatim refresh --website` |
 533
 534 Enable to search elements just within countries.
 535
 536 When enabled, if, despite not finding a point within the static grid of countries, it
 537 finds a geometry of a region, do not return the geometry.
 538 Return "Unable to geocode" instead.
 539
 540
 541 #### NOMINATIM_SERVE_LEGACY_URLS
 542
 543 | Summary            |                                                     |
 544 | --------------     | --------------------------------------------------- |
 545 | **Description:**   | Enable serving via URLs with a .php suffix |
 546 | **Format:**        | boolean |
 547 | **Default:**       | yes |
 548 | **Comment:**       | Python frontend only |
 549
 550 When enabled, then endpoints are reachable as `/<name>` as well as `/<name>.php`.
 551 This can be useful when you want to be backwards-compatible with previous
 552 versions of Nominatim.
 553
 554
 555 #### NOMINATIM_API_POOL_SIZE
 556
 557 | Summary            |                                                     |
 558 | --------------     | --------------------------------------------------- |
 559 | **Description:**   | Number of parallel database connections per worker |
 560 | **Format:**        | number |
 561 | **Default:**       | 10 |
 562 | **Comment:**       | Python frontend only |
 563
 564 Sets the maximum number of database connections available for a single instance
 565 of Nominatim. When configuring the maximum number of connections that your
 566 PostgreSQL database can handle, you need at least
 567 `NOMINATIM_API_POOL_SIZE` * `<number of configured workers>` connections.
 568 For configuring the number of workers, refer to the section about
 569 [Deploying the Python frontend](../admin/Deployment-Python.md).
 570
 571 #### NOMINATIM_QUERY_TIMEOUT
 572
 573 | Summary            |                                                     |
 574 | --------------     | --------------------------------------------------- |
 575 | **Description:**   | Timeout for SQL queries to the database |
 576 | **Format:**        | number (seconds) |
 577 | **Default:**       | 10 |
 578 | **Comment:**       | Python frontend only |
 579
 580 When this timeout is set, then all SQL queries that run longer than the
 581 specified numbers of seconds will be cancelled and the user receives a
 582 timeout exceptions. Users of the API see a 503 HTTP error.
 583
 584 The timeout does ont apply when using the
 585 [low-level DB access](../library/Low-Level-DB-Access.md)
 586 of the library. A timeout can be manually set, if required.
 587
 588
 589 #### NOMINATIM_REQUEST_TIMEOUT
 590
 591 | Summary            |                                                     |
 592 | --------------     | --------------------------------------------------- |
 593 | **Description:**   | Timeout for search queries |
 594 | **Format:**        | number (seconds) |
 595 | **Default:**       | 60 |
 596 | **Comment:**       | Python frontend only |
 597
 598 When this timeout is set, a search query will finish sending queries
 599 to the database after the timeout has passed and immediately return the
 600 results gathered so far.
 601
 602 Note that under high load you may observe that users receive different results
 603 than usual without seeing an error. This may cause some confusion.
 604
 605 #### NOMINATIM_OUTPUT_NAMES
 606
 607 | Summary            |                                                     |
 608 | --------------     | --------------------------------------------------- |
 609 | **Description:**   | Specifies order of name tags |
 610 | **Format:**        | string: comma-separated list of tag names |
 611 | **Default:**       | name:XX,name,brand,official_name:XX,short_name:XX,official_name,short_name,ref |
 612
 613 Specifies the order in which different name tags are used.
 614 The values in this list determine the preferred order of name variants,
 615 including language-specific names (in OSM: the name tag with and without any language suffix).
 616
 617 Comma-separated list, where :XX stands for language suffix
 618 (e.g. name:en) and no :XX stands for general tags (e.g. name).
 619
 620 See also [NOMINATIM_DEFAULT_LANGUAGE](#nominatim_default_language).
 621
 622 !!! note
 623     If NOMINATIM_OUTPUT_NAMES = `name:XX,name,short_name:XX,short_name` the search follows
 624
 625         ```
 626         'name', 'short_name'
 627         ```
 628
 629     if we have no preferred language order for showing search results.
 630
 631     For languages ['en', 'es'] the search follows
 632
 633         ```
 634         'name:en', 'name:es',
 635         'name',
 636         'short_name:en', 'short_name:es',
 637         'short_name'
 638         ```
 639
 640     For those familiar with the internal implementation, the `_place_*` expansion is added, but to simplify, it is not included in this example.
 641
 642 ### Logging Settings
 643
 644 #### NOMINATIM_LOG_FILE
 645
 646 | Summary            |                                                     |
 647 | --------------     | --------------------------------------------------- |
 648 | **Description:**   | Log requests into a file |
 649 | **Format:**        | path |
 650 | **Default:**       | _empty_ (logging disabled) |
 651
 652 Enable logging of requests into a file with this setting by setting the log
 653 file where to log to. A relative file name is assumed to be relative to
 654 the project directory. The format of the log output can be set
 655 with NOMINATIM_LOG_FORMAT.
 656
 657 #### NOMINATIM_LOG_FORMAT
 658
 659 | Summary            |                                                     |
 660 | --------------     | --------------------------------------------------- |
 661 | **Description:**   | Log requests into a file |
 662 | **Format:**        | [Python String Format](https://docs.python.org/3/library/string.html#formatstrings) string |
 663 | **Default:**       | `[{start}] {total_time:.4f} {results_total} {endpoint} "{query_string}"` |
 664
 665 Describes the content of a log line for a single request. The format
 666 must be readable by Python's format function. Nominatim provides a number
 667 of metrics than can be logged. The default set of metrics is the following:
 668
 669 /// html | div.simple-table
 670 | name            | type   | Description |
 671 | --------------- | ------ | ------------|
 672 | start           | time   | Point in time when the request arrived. |
 673 | end             | time   | Point in time when the request was done. |
 674 | query_start     | time   | Point in time when processing started. |
 675 | total_time      | float  | Total time in seconds to handle the request. |
 676 | wait_time       | float  | Time in seconds the request waited for a database connection to be available. |
 677 | query_time      | float  | Total time in seconds to process the request once a connection was available. |
 678 | results_total   | int    | Number of results found. |
 679 | endpoint        | string | API endpoint used. |
 680 | query_string    | string | Raw query string received. |
 681 ///
 682
 683 Variables of type 'time' contain a UTC timestamp string in ISO format.
 684
 685 Nominatim also exposes additional metrics to help with development. These
 686 are subject to change between versions:
 687
 688 /// html | div.simple-table
 689 | name                      | type   | Description |
 690 | ------------------------- | ------ | ------------|
 691 | search_rounds             | int    | Total number of searches executed for the request. |
 692 | search_min_penalty        | float  | Minimal possible penalty for the request. |
 693 | search_first_result_round | int    | Number of first search to yield any result. |
 694 | search_min_result_penalty | float  | Minimal penalty by a result found. |
 695 | search_best_penalty_round | int    | Search round that yielded the best penalty result. |
 696 ///
 697
 698
 699 #### NOMINATIM_DEBUG_SQL
 700
 701 | Summary            |                                                     |
 702 | --------------     | --------------------------------------------------- |
 703 | **Description:**   | Enable printing of raw SQL by SQLAlchemy |
 704 | **Format:**        | boolean |
 705 | **Default:**       | no |
 706 | **Comment:**       | **For developers only.** |
 707
 708 This settings enables
 709 [SQL debugging](https://docs.sqlalchemy.org/en/20/core/engines.html#dbengine-logging)
 710 by SQLAlchemy. This can be helpful when debugging some bugs with internal
 711 query handling. It should only be used together with the CLI query functions.
 712 Enabling it for server mode may have unintended consequences. Use the `debug`
 713 parameter instead, which prints information on how the search is executed
 714 including SQL statements.