docs/admin/Import.md

   1 # Importing the Database
   2
   3 The following instructions explain how to create a Nominatim database
   4 from an OSM planet file. It is assumed that you have already successfully
   5 installed the Nominatim software itself and the `nominatim` tool can be found
   6 in your `PATH`. If this is not the case, return to the
   7 [installation page](Installation.md).
   8
   9 ## Creating the project directory
  10
  11 Before you start the import, you should create a project directory for your
  12 new database installation. This directory receives all data that is related
  13 to a single Nominatim setup: configuration, extra data, etc. Create a project
  14 directory apart from the Nominatim software and change into the directory:
  15
  16 ```
  17 mkdir ~/nominatim-project
  18 cd ~/nominatim-project
  19 ```
  20
  21 In the following, we refer to the project directory as `$PROJECT_DIR`. To be
  22 able to copy&paste instructions, you can export the appropriate variable:
  23
  24 ```
  25 export PROJECT_DIR=~/nominatim-project
  26 ```
  27
  28 The Nominatim tool assumes per default that the current working directory is
  29 the project directory but you may explicitly state a different directory using
  30 the `--project-dir` parameter. The following instructions assume that you run
  31 all commands from the project directory.
  32
  33 !!! tip "Migration Tip"
  34
  35     Nominatim used to be run directly from the build directory until version 3.6.
  36     Essentially, the build directory functioned as the project directory
  37     for the database installation. This setup still works and can be useful for
  38     development purposes. It is not recommended anymore for production setups.
  39     Create a project directory that is separate from the Nominatim software.
  40
  41 ### Configuration setup in `.env`
  42
  43 The Nominatim server can be customized via an `.env` configuration file in the
  44 project directory. This is a file in [dotenv](https://github.com/theskumar/python-dotenv)
  45 format which looks the same as variable settings in a standard shell environment.
  46 You can also set the same configuration via environment variables. All
  47 settings have a `NOMINATIM_` prefix to avoid conflicts with other environment
  48 variables.
  49
  50 There are lots of configuration settings you can tweak. A full reference
  51 can be found in the chapter [Configuration Settings](../customize/Settings.md).
  52 Most should have a sensible default.
  53
  54 #### Flatnode files
  55
  56 If you plan to import a large dataset (e.g. Europe, North America, planet),
  57 you should also enable flatnode storage of node locations. With this
  58 setting enabled, node coordinates are stored in a simple file instead
  59 of the database. This will save you import time and disk storage.
  60 Add to your `.env`:
  61
  62     NOMINATIM_FLATNODE_FILE="/path/to/flatnode.file"
  63
  64 Replace the second part with a suitable path on your system and make sure
  65 the directory exists. There should be at least 75GB of free space.
  66
  67 ## Downloading additional data
  68
  69 ### Wikipedia/Wikidata rankings
  70
  71 Wikipedia can be used as an optional auxiliary data source to help indicate
  72 the importance of OSM features. Nominatim will work without this information
  73 but it will improve the quality of the results if this is installed.
  74 This data is available as a binary download. Put it into your project directory:
  75
  76     cd $PROJECT_DIR
  77     wget https://nominatim.org/data/wikimedia-importance.csv.gz
  78     wget -O secondary_importance.sql.gz https://nominatim.org/data/wikimedia-secondary-importance.sql.gz
  79
  80 The files are about 400MB and add around 4GB to the Nominatim database. For
  81 more information about importance,
  82 see [Importance Customization](../customize/Importance.md).
  83
  84 !!! tip
  85     If you forgot to download the wikipedia rankings, then you can
  86     also add importances after the import. Download the SQL files, then
  87     run `nominatim refresh --wiki-data --secondary-importance --importance`.
  88     Updating importances for a planet will take a couple of hours.
  89
  90 ### External postcodes
  91
  92 Nominatim can use postcodes from an external source to improve searching with
  93 postcodes. We provide precomputed postcodes sets for the US (using TIGER data)
  94 and the UK (using the [CodePoint OpenData set](https://osdatahub.os.uk/downloads/open/CodePointOpen).
  95 This data can be optionally downloaded into the project directory:
  96
  97     cd $PROJECT_DIR
  98     wget https://nominatim.org/data/gb_postcodes.csv.gz
  99     wget https://nominatim.org/data/us_postcodes.csv.gz
 100
 101 You can also add your own custom postcode sources, see
 102 [Customization of postcodes](../customize/Postcodes.md).
 103
 104 ## Choosing the data to import
 105
 106 In its default setup Nominatim is configured to import the full OSM data
 107 set for the entire planet. Such a setup requires a powerful machine with
 108 at least 64GB of RAM and around 900GB of SSD hard disks. Depending on your
 109 use case there are various ways to reduce the amount of data imported. This
 110 section discusses these methods. They can also be combined.
 111
 112 ### Using an extract
 113
 114 If you only need geocoding for a smaller region, then precomputed OSM extracts
 115 are a good way to reduce the database size and import time.
 116 [Geofabrik](https://download.geofabrik.de) offers extracts for most countries.
 117 They even have daily updates which can be used with the update process described
 118 [in the next section](Update.md). There are also
 119 [other providers for extracts](https://wiki.openstreetmap.org/wiki/Planet.osm#Downloading).
 120
 121 Please be aware that some extracts are not cut exactly along the country
 122 boundaries. As a result some parts of the boundary may be missing which means
 123 that Nominatim cannot compute the areas for some administrative areas.
 124
 125 ### Dropping Data Required for Dynamic Updates
 126
 127 About half of the data in Nominatim's database is not really used for serving
 128 the API. It is only there to allow the data to be updated from the latest
 129 changes from OSM. For many uses these dynamic updates are not really required.
 130 If you don't plan to apply updates, you can run the import with the
 131 `--no-updates` parameter. This will drop the dynamic part of the database as
 132 soon as it is not required anymore.
 133
 134 You can also drop the dynamic part later using the following command:
 135
 136 ```
 137 nominatim freeze
 138 ```
 139
 140 Note that you still need to provide for sufficient disk space for the initial
 141 import. So this option is particularly interesting if you plan to transfer the
 142 database or reuse the space later.
 143
 144 !!! warning
 145     The data structure for updates are also required when adding additional data
 146     after the import, for example [TIGER housenumber data](../customize/Tiger.md).
 147     If you plan to use those, you must not use the `--no-updates` parameter.
 148     Do a normal import, add the external data and once you are done with
 149     everything run `nominatim freeze`.
 150
 151
 152 ### Reverse-only Imports
 153
 154 If you only want to use the Nominatim database for reverse lookups or
 155 if you plan to use the installation only for exports to a
 156 [photon](https://photon.komoot.io/) database, then you can set up a database
 157 without search indexes. Add `--reverse-only` to your setup command above.
 158
 159 This saves about 5% of disk space, import time won't be significant faster.
 160
 161 ### Filtering Imported Data
 162
 163 Nominatim normally sets up a full search database containing administrative
 164 boundaries, places, streets, addresses and POI data. There are also other
 165 import styles available which only read selected data:
 166
 167 * **admin**
 168   Only import administrative boundaries and places.
 169 * **street**
 170   Like the admin style but also adds streets.
 171 * **address**
 172   Import all data necessary to compute addresses down to house number level.
 173 * **full**
 174   Default style that also includes points of interest.
 175 * **extratags**
 176   Like the full style but also adds most of the OSM tags into the extratags
 177   column.
 178
 179 The style can be changed with the configuration `NOMINATIM_IMPORT_STYLE`.
 180
 181 To give you an idea of the impact of using the different styles, the table
 182 below gives rough estimates of the final database size after import of a
 183 2020 planet and after using the `--drop` option. It also shows the time
 184 needed for the import on a machine with 64GB RAM, 4 CPUS and NVME disks.
 185 Note that the given sizes are just an estimate meant for comparison of
 186 style requirements. Your planet import is likely to be larger as the
 187 OSM data grows with time.
 188
 189 style     | Import time  |  DB size   |  after drop
 190 ----------|--------------|------------|------------
 191 admin     |    4h        |  215 GB    |   20 GB
 192 street    |   22h        |  440 GB    |  185 GB
 193 address   |   36h        |  545 GB    |  260 GB
 194 full      |   54h        |  640 GB    |  330 GB
 195 extratags |   54h        |  650 GB    |  340 GB
 196
 197 You can also customize the styles further.
 198 A [description of the style format](../customize/Import-Styles.md)
 199 can be found in the customization guide.
 200
 201 ## Initial import of the data
 202
 203 !!! danger "Important"
 204     First try the import with a small extract, for example from
 205     [Geofabrik](https://download.geofabrik.de).
 206
 207 Download the data to import. Then issue the following command
 208 from the **project directory** to start the import:
 209
 210 ```sh
 211 nominatim import --osm-file <data file> 2>&1 | tee setup.log
 212 ```
 213
 214 The **project directory** is the one that you have set up at the beginning.
 215 See [creating the project directory](#creating-the-project-directory).
 216
 217 ### Notes on full planet imports
 218
 219 Even on a perfectly configured machine
 220 the import of a full planet takes around 2 days. Once you see messages
 221 with `Rank .. ETA` appear, the indexing process has started. This part takes
 222 the most time. There are 30 ranks to process. Rank 26 and 30 are the most complex.
 223 They take each about a third of the total import time. If you have not reached
 224 rank 26 after two days of import, it is worth revisiting your system
 225 configuration as it may not be optimal for the import.
 226
 227 ### Notes on memory usage
 228
 229 In the first step of the import Nominatim uses [osm2pgsql](https://osm2pgsql.org)
 230 to load the OSM data into the PostgreSQL database. This step is very demanding
 231 in terms of RAM usage. osm2pgsql and PostgreSQL are running in parallel at
 232 this point. PostgreSQL blocks at least the part of RAM that has been configured
 233 with the `shared_buffers` parameter during
 234 [PostgreSQL tuning](Installation.md#tuning-the-postgresql-database)
 235 and needs some memory on top of that. osm2pgsql needs at least 2GB of RAM for
 236 its internal data structures, potentially more when it has to process very large
 237 relations. In addition it needs to maintain a cache for node locations. The size
 238 of this cache can be configured with the parameter `--osm2pgsql-cache`.
 239
 240 When importing with a flatnode file, it is best to disable the node cache
 241 completely and leave the memory for the flatnode file. Nominatim will do this
 242 by default, so you do not need to configure anything in this case.
 243
 244 For imports without a flatnode file, set `--osm2pgsql-cache` approximately to
 245 the size of the OSM pbf file you are importing. The size needs to be given in
 246 MB. Make sure you leave enough RAM for PostgreSQL and osm2pgsql as mentioned
 247 above. If the system starts swapping or you are getting out-of-memory errors,
 248 reduce the cache size or even consider using a flatnode file.
 249
 250
 251 ### Testing the installation
 252
 253 Run this script to verify that all required tables and indices got created
 254 successfully.
 255
 256 ```sh
 257 nominatim admin --check-database
 258 ```
 259
 260 If you have installed the `nominatim-api` package, then you can try out
 261 your installation by executing a simple query on the command line:
 262
 263 ``` sh
 264 nominatim search --query Berlin
 265 ```
 266
 267 or, when you have a reverse-only installation:
 268
 269 ``` sh
 270 nominatim reverse --lat 51 --lon 45
 271 ```
 272
 273 If you want to run Nominatim as a service, make sure you have installed
 274 the right packages as per [Installation](Installation.md#software).
 275
 276 #### Testing the Python frontend
 277
 278 To run the test server against the Python frontend, you must choose a
 279 web framework to use, either starlette or falcon. Make sure the appropriate
 280 packages are installed. Then run
 281
 282 ``` sh
 283 nominatim serve
 284 ```
 285
 286 or, if you prefer to use Starlette instead of Falcon as webserver,
 287
 288 ``` sh
 289 nominatim serve --engine starlette
 290 ```
 291
 292 Go to `http://localhost:8088/status` and you should see the message `OK`.
 293 You can also run a search query, e.g. `http://localhost:8088/search?q=Berlin`
 294 or, for reverse-only installations a reverse query,
 295 e.g. `http://localhost:8088/reverse?lat=27.1750090510034&lon=78.04209025`.
 296
 297 Do not use this test server in production.
 298 To run Nominatim via webservers like Apache or nginx, please continue reading
 299 [Deploy the Python frontend](Deployment-Python.md).
 300
 301
 302 ## Enabling search by category phrases
 303
 304 To be able to search for places by their type using
 305 [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
 306 you also need to import these key phrases like this:
 307
 308 ```sh
 309 nominatim special-phrases --import-from-wiki
 310 ```
 311
 312 Note that this command downloads the phrases from the wiki link above. You
 313 need internet access for the step.
 314
 315 You can also import special phrases from a csv file, for more
 316 information please see the [Customization part](../customize/Special-Phrases.md).