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