docs/customize/Postcodes.md

   1 # External postcode data
   2
   3 Nominatim creates a table of known postcode centroids and geometries during import.
   4 This table is used for searches of postcodes and for adding postcodes to places where
   5 the OSM data does not provide one. These postcode centroids are mainly computed
   6 from the OSM data itself. In addition, Nominatim supports reading postcode information
   7 from external files to supplement the postcodes that are missing in OSM.
   8
   9 ## Supported file formats
  10
  11 Nominatim supports 2 data formats for external import:
  12
  13 ### JSONL format
  14
  15 The JSONL format may contain the postcode data along with a POLYGON or MULTIPOLYGON geometry
  16 of the postcode area. To enable external postcode support, put one file per country into
  17 your project directory and name it `<CC>_postcodes_geometry.<ext>`. `<CC>` must be the
  18 two-letter country code for which to apply the file. File type may be either `.jsonl` or
  19 `.jsonl.gz` (gzip compressed). The file must be in UTF-8 encoding and contain one JSON object
  20 per line with the following structure:
  21
  22 #### GeoJSON Feature
  23
  24 A standard [RFC7946](https://geojson.org) GeoJSON Feature object.
  25
  26 * `geometry`: (required) A GeoJSON geometry (Polygon/MultiPolygon).
  27 * `properties`: (required) An object containing:
  28   * `postcode`: (required) The postcode string.
  29   * `lat`, `lon`: (optional) Coordinates for the centroid. If not provided, the centroid
  30   is computed from the geometry.
  31
  32 ### CSV format
  33
  34 To enable external postcode support, put one file per country into
  35 your project directory and name it `<CC>_postcodes.<ext>`. `<CC>` must be the
  36 two-letter country code for which to apply the file. File type may be either `.csv` or `.csv.gz`
  37 (gzip compressed). The CSV file must use commas as a delimiter and have a header line. Nominatim
  38 expects three columns to be present: `postcode`, `lat` and `lon`. All other columns are ignored.
  39 `lon` and `lat` must describe the x and y coordinates of the postcode centroids in WGS84.
  40
  41 The postcode area is assumed to be in a buffer around the centroid (typically 5km).
  42
  43 ## Usage
  44
  45 As a rule, the external postcode data should be put into the project directory
  46 **before** starting the initial import. Still, you can add, remove and update the
  47 external postcode data at any time. Simply run:
  48
  49 ```
  50 nominatim refresh --postcodes
  51 ```
  52
  53 to make the changes visible in your database. Be aware, however, that the changes
  54 only have an immediate effect on searches for postcodes. Postcodes that were
  55 added to places are only updated, when they are reindexed. That usually happens
  56 only during replication updates.