docs/customize/Postcodes.md

   1 # External postcode data
   2
   3 Nominatim creates a table of known postcode centroids during import. This table
   4 is used for searches of postcodes and for adding postcodes to places where the
   5 OSM data does not provide one. These postcode centroids are mainly computed
   6 from the OSM data itself. In addition, Nominatim supports reading postcode
   7 information from an external CSV file, to supplement the postcodes that are
   8 missing in OSM.
   9
  10 To enable external postcode support, simply put one CSV file per country into
  11 your project directory and name it `<CC>_postcodes.csv`. `<CC>` must be the
  12 two-letter country code for which to apply the file. The file may also be
  13 gzipped. Then it must be called `<CC>_postcodes.csv.gz`.
  14
  15 The CSV file must use commas as a delimiter and have a header line. Nominatim
  16 expects three columns to be present: `postcode`, `lat` and `lon`. All other
  17 columns are ignored. `lon` and `lat` must describe the x and y coordinates of the
  18 postcode centroids in WGS84.
  19
  20 The postcode files are loaded only when there is data for the given country
  21 in your database. For example, if there is a `us_postcodes.csv` file in your
  22 project directory but you import only an excerpt of Italy, then the US postcodes
  23 will simply be ignored.
  24
  25 As a rule, the external postcode data should be put into the project directory
  26 **before** starting the initial import. Still, you can add, remove and update the
  27 external postcode data at any time. Simply
  28 run:
  29
  30 ```
  31 nominatim refresh --postcodes
  32 ```
  33
  34 to make the changes visible in your database. Be aware, however, that the changes
  35 only have an immediate effect on searches for postcodes. Postcodes that were
  36 added to places are only updated, when they are reindexed. That usually happens
  37 only during replication updates.