From: Sarah Hoffmann <lonvia@denofr.de>
Date: Thu, 29 Sep 2022 12:55:46 +0000 (+0200)
Subject: docs: add customization hints for secondary importance
X-Git-Tag: v4.2.0~25^2
X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/b3abb355ebcf06fe47d450e7c2fc5074ae6f4b7c?ds=sidebyside;hp=-c

docs: add customization hints for secondary importance

Removing the download links for now as the tile importance
is still too experimental.
---

b3abb355ebcf06fe47d450e7c2fc5074ae6f4b7c
diff --git a/docs/admin/Import.md b/docs/admin/Import.md
index 91b92728..8b6d6baa 100644
--- a/docs/admin/Import.md
+++ b/docs/admin/Import.md
@@ -78,27 +78,10 @@ This data is available as a binary download. Put it into your project directory:
 
 The file is about 400MB and adds around 4GB to the Nominatim database.
 
-### OSM views 
-OSM publishes aggregate map access numbers that are generated based on the users’ 
-behavior when viewing locations on the map. This data is also optional and 
-it complements wikipedia/wikidata rankings to further enhance the search results
-if added.
-OSM views data is avalaible as a GeoTIFF file. Put it into your project directory:
-
-    cd $PROJECT_DIR
-    wget https://qrank.wmcloud.org/download/osmviews.tiff
-
-The file is about 380MB and adds around 4GB to the Nominatim database. Importing
-OSM views into Nominatim takes a little over 3 hours.
-
-!!! warning
-    Importing OSM views is currently an experimental feature. OSM views data are
-    not yet included in the importance values calculations.
-
 !!! tip
-    If you forgot to download the wikipedia rankings or OSM views, then you can 
-    also add importances after the import. To add both, download their files, then 
-    run `nominatim refresh --wiki-data --osm-views --importance`. Updating 
+    If you forgot to download the wikipedia rankings, then you can
+    also add importances after the import. Download the SQL files, then
+    run `nominatim refresh --wiki-data --importance`. Updating
     importances for a planet will take a couple of hours.
 
 ### External postcodes
diff --git a/docs/customize/Importance.md b/docs/customize/Importance.md
new file mode 100644
index 00000000..d12bfc86
--- /dev/null
+++ b/docs/customize/Importance.md
@@ -0,0 +1,49 @@
+## Importance
+
+Search requests can yield multiple results which match equally well with
+the original query. In such case Nominatim needs to order the results
+according to a different criterion: importance. This is a measure for how
+likely it is that a user will search for a given place. This section explains
+the sources Nominatim uses for computing importance of a place and how to
+customize them.
+
+### How importance is computed
+
+The main value for importance is derived from page ranking values for Wikipedia
+pages for a place. For places that do not have their own
+Wikipedia page, a formula is used that derives a static importance from the
+places [search rank](../customize/Ranking#search-rank).
+
+In a second step, a secondary importance value is added which is meant to
+represent how well-known the general area is where the place is located. It
+functions as a tie-breaker between places with very similar primary
+importance values.
+
+nominatim.org has preprocessed importance tables for the
+[primary Wikipedia rankings](https://nominatim.org/data/wikimedia-importance.sql.gz)
+and for a secondary importance based on the number of tile views on openstreetmap.org.
+
+### Customizing secondary importance
+
+The secondary importance is implemented as a simple
+[Postgis raster](https://postgis.net/docs/raster.html) table, where Nominatim
+looks up the value for the coordinates of the centroid of a place. You can
+provide your own secondary importance raster in form of an SQL file named
+`secondary_importance.sql.gz` in your project directory.
+
+The SQL file needs to drop and (re)create a table `secondary_importance` which
+must as a minimum contain a column `rast` of type `raster`. The raster must
+be in EPSG:4326 and contain 16bit unsigned ints
+(`raster_constraint_pixel_types(rast) = '{16BUI}'). Any other columns in the
+table will be ignored. You must furthermore create an index as follows:
+
+```
+CREATE INDEX ON secondary_importance USING gist(ST_ConvexHull(gist))
+```
+
+The following raster2pgsql command will create a table that conforms to
+the requirements:
+
+```
+raster2pgsql -I -C -Y -d -t 128x128 input.tiff public.secondary_importance
+```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index e89c32d5..ab7dec30 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -30,6 +30,7 @@ nav:
         - 'Configuration Settings': 'customize/Settings.md'
         - 'Per-Country Data': 'customize/Country-Settings.md'
         - 'Place Ranking' : 'customize/Ranking.md'
+        - 'Importance' : 'customize/Importance.md'
         - 'Tokenizers' : 'customize/Tokenizers.md'
         - 'Special Phrases': 'customize/Special-Phrases.md'
         - 'External data: US housenumbers from TIGER': 'customize/Tiger.md'