docs/admin/Customization.md

   1 # Customization of the Database
   2
   3 This section explains in detail how to configure a Nominatim import and
   4 the various means to use external data.
   5
   6 ## External postcode data
   7
   8 Nominatim creates a table of known postcode centroids during import. This table
   9 is used for searches of postcodes and for adding postcodes to places where the
  10 OSM data does not provide one. These postcode centroids are mainly computed
  11 from the OSM data itself. In addition, Nominatim supports reading postcode
  12 information from an external CSV file, to supplement the postcodes that are
  13 missing in OSM.
  14
  15 To enable external postcode support, simply put one CSV file per country into
  16 your project directory and name it `<CC>_postcodes.csv`. `<CC>` must be the
  17 two-letter country code for which to apply the file. The file may also be
  18 gzipped. Then it must be called `<CC>_postcodes.csv.gz`.
  19
  20 The CSV file must use commas as a delimiter and have a header line. Nominatim
  21 expects three columns to be present: `postcode`, `lat` and `lon`. All other
  22 columns are ignored. `lon` and `lat` must describe the x and y coordinates of the
  23 postcode centroids in WGS84.
  24
  25 The postcode files are loaded only when there is data for the given country
  26 in your database. For example, if there is a `us_postcodes.csv` file in your
  27 project directory but you import only an excerpt of Italy, then the US postcodes
  28 will simply be ignored.
  29
  30 As a rule, the external postcode data should be put into the project directory
  31 **before** starting the initial import. Still, you can add, remove and update the
  32 external postcode data at any time. Simply
  33 run:
  34
  35 ```
  36 nominatim refresh --postcodes
  37 ```
  38
  39 to make the changes visible in your database. Be aware, however, that the changes
  40 only have an immediate effect on searches for postcodes. Postcodes that were
  41 added to places are only updated, when they are reindexed. That usually happens
  42 only during replication updates.
  43
  44 ## Installing Tiger housenumber data for the US
  45
  46 Nominatim is able to use the official [TIGER](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html)
  47 address set to complement the OSM house number data in the US. You can add
  48 TIGER data to your own Nominatim instance by following these steps. The
  49 entire US adds about 10GB to your database.
  50
  51   1. Get preprocessed TIGER 2021 data:
  52
  53         cd $PROJECT_DIR
  54         wget https://nominatim.org/data/tiger2021-nominatim-preprocessed.csv.tar.gz
  55
  56   2. Import the data into your Nominatim database:
  57
  58         nominatim add-data --tiger-data tiger2021-nominatim-preprocessed.csv.tar.gz
  59
  60   3. Enable use of the Tiger data in your `.env` by adding:
  61
  62         echo NOMINATIM_USE_US_TIGER_DATA=yes >> .env
  63
  64   4. Apply the new settings:
  65
  66         nominatim refresh --functions
  67
  68
  69 See the [developer's guide](../develop/data-sources.md#us-census-tiger) for more
  70 information on how the data got preprocessed.
  71
  72 ## Special phrases import
  73
  74 As described in the [Importation chapter](Import.md), it is possible to
  75 import special phrases from the wiki with the following command:
  76
  77 ```sh
  78 nominatim special-phrases --import-from-wiki
  79 ```
  80
  81 But, it is also possible to import some phrases from a csv file.
  82 To do so, you have access to the following command:
  83
  84 ```sh
  85 nominatim special-phrases --import-from-csv <csv file>
  86 ```
  87
  88 Note that the two previous import commands will update the phrases from your database.
  89 This means that if you import some phrases from a csv file, only the phrases
  90 present in the csv file will be kept into the database. All other phrases will
  91 be removed.
  92
  93 If you want to only add new phrases and not update the other ones you can add
  94 the argument `--no-replace` to the import command. For example:
  95
  96 ```sh
  97 nominatim special-phrases --import-from-csv <csv file> --no-replace
  98 ```
  99
 100 This will add the phrases present in the csv file into the database without
 101 removing the other ones.