From: Sarah Hoffmann Date: Thu, 13 May 2021 10:04:47 +0000 (+0200) Subject: add documentation for external postcode feature X-Git-Tag: v4.0.0~87^2~2 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/41b9bc99843ce8ce648ef695e2d4f8b87f15db79 add documentation for external postcode feature --- diff --git a/docs/admin/Customization.md b/docs/admin/Customization.md new file mode 100644 index 00000000..10c8d3dd --- /dev/null +++ b/docs/admin/Customization.md @@ -0,0 +1,71 @@ +# Customization of the Database + +This section explains in detail how to configure a Nominatim import and +the various means to use external data. + +## External postcode data + +Nominatim creates a table of known postcode centroids during import. This table +is used for searches of postcodes and for adding postcodes to places where the +OSM data does not provide one. These postcode centroids are mainly computed +from the OSM data itself. In addition, Nominatim supports reading postcode +information from an external CSV file, to supplement the postcodes that are +missing in OSM. + +To enable external postcode support, simply put one CSV file per country into +your project directory and name it `_postcodes.csv`. `` must be the +two-letter country code for which to apply the file. The file may also be +gzipped. Then it must be called `_postcodes.csv.gz`. + +The CSV file must use commas as a delimiter and have a header line. Nominatim +expects three columns to be present: `postcode`, `lat` and `lon`. All other +columns are ignored. `lon` and `lat` must describe the x and y coordinates of the +postcode centroids in WGS84. + +The postcode files are loaded only when there is data for the given country +in your database. For example, if there is a `us_postcodes.csv` file in your +project directory but you import only an excerpt of Italy, then the US postcodes +will simply be ignored. + +As a rule, the external postcode data should be put into the project directory +**before** starting the initial import. Still, you can add, remove and update the +external postcode data at any time. Simply +run: + +``` +nominatim refresh --postcodes +``` + +to make the changes visible in your database. Be aware, however, that the changes +only have an immediate effect on searches for postcodes. Postcodes that were +added to places are only updated, when they are reindexed. That usually happens +only during replication updates. + +## Installing Tiger housenumber data for the US + +Nominatim is able to use the official [TIGER](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html) +address set to complement the OSM house number data in the US. You can add +TIGER data to your own Nominatim instance by following these steps. The +entire US adds about 10GB to your database. + + 1. Get preprocessed TIGER 2020 data: + + cd $PROJECT_DIR + wget https://nominatim.org/data/tiger2020-nominatim-preprocessed.tar.gz + + 2. Import the data into your Nominatim database: + + nominatim add-data --tiger-data tiger2020-nominatim-preprocessed.tar.gz + + 3. Enable use of the Tiger data in your `.env` by adding: + + echo NOMINATIM_USE_US_TIGER_DATA=yes >> .env + + 4. Apply the new settings: + + nominatim refresh --functions + + +See the [developer's guide](../develop/data-sources.md#us-census-tiger) for more +information on how the data got preprocessed. + diff --git a/docs/admin/Import.md b/docs/admin/Import.md index 6b417ff2..2a9a86e6 100644 --- a/docs/admin/Import.md +++ b/docs/admin/Import.md @@ -83,15 +83,19 @@ The file is about 400MB and adds around 4GB to the Nominatim database. `nominatim refresh --wiki-data --importance`. Updating importances for a planet can take a couple of hours. -### Great Britain, USA postcodes +### External postcodes -Nominatim can use postcodes from an external source to improve searches that -involve a GB or US postcode. This data can be optionally downloaded into the -project directory: +Nominatim can use postcodes from an external source to improve searching with +postcodes. We provide precomputed postcodes sets for the US (using TIGER data) +and the UK (using the [CodePoint OpenData set](https://osdatahub.os.uk/downloads/open/CodePointOpen). +This data can be optionally downloaded into the project directory: cd $PROJECT_DIR - wget https://www.nominatim.org/data/gb_postcode_data.sql.gz - wget https://www.nominatim.org/data/us_postcode_data.sql.gz + wget https://www.nominatim.org/data/gb_postcodes.csv.gz + wget https://www.nominatim.org/data/us_postcodes.csv.gz + +You can also add your own custom postcode sources, see +[Customization of postcodes](Customization.md#external-postcode-data). ## Choosing the data to import @@ -274,33 +278,3 @@ you also need to import these key phrases like this: Note that this command downloads the phrases from the wiki link above. You need internet access for the step. - - -## Installing Tiger housenumber data for the US - -Nominatim is able to use the official [TIGER](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html) -address set to complement the OSM house number data in the US. You can add -TIGER data to your own Nominatim instance by following these steps. The -entire US adds about 10GB to your database. - - 1. Get preprocessed TIGER 2020 data: - - cd $PROJECT_DIR - wget https://nominatim.org/data/tiger2020-nominatim-preprocessed.tar.gz - - 2. Import the data into your Nominatim database: - - nominatim add-data --tiger-data tiger2020-nominatim-preprocessed.tar.gz - - 3. Enable use of the Tiger data in your `.env` by adding: - - echo NOMINATIM_USE_US_TIGER_DATA=yes >> .env - - 4. Apply the new settings: - - nominatim refresh --functions - - -See the [developer's guide](../develop/data-sources.md#us-census-tiger) for more -information on how the data got preprocessed. - diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b055e9f0..ef2ef9a5 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -19,6 +19,7 @@ pages: - 'Import' : 'admin/Import.md' - 'Update' : 'admin/Update.md' - 'Deploy' : 'admin/Deployment.md' + - 'Customize Imports' : 'admin/Customization.md' - 'Nominatim UI' : 'admin/Setup-Nominatim-UI.md' - 'Advanced Installations' : 'admin/Advanced-Installations.md' - 'Migration from older Versions' : 'admin/Migration.md'