documentation: new page explaining calculated postcodes

docs/develop/Documentation.md

@@ -6,31 +6,27 @@ To preview local changes:
 
 1. Install MkDocs
 
-   ```
+    ```
-   pip3 install --user mkdocs 
+    pip3 install --user mkdocs 
-   ```
+    ```
 
 
 2. In build directory run
 
-   ```
+        make doc
-   make doc
+        INFO - Cleaning site directory
-   INFO - Cleaning site directory
+        INFO - Building documentation to directory: /home/vagrant/build/site-html 
-   INFO - Building documentation to directory: /home/vagrant/build/site-html 
-   ```
 
-   This runs `mkdocs build` plus extra transformion of some files and adds symlinks (see `CMakeLists.txt` for the exact steps).
+    This runs `mkdocs build` plus extra transformion of some files and adds symlinks (see `CMakeLists.txt` for the exact steps).
 
 
 3. Start webserver for local testing
 
-   ```
+        mkdocs serve
-   mkdocs serve
+        [server:296] Serving on http://127.0.0.1:8000
-   [server:296] Serving on http://127.0.0.1:8000
+        [handlers:62] Start watching changes
-   [handlers:62] Start watching changes
-   ```
 
-   If you develop inside a Vagrant virtual machine:
+    If you develop inside a Vagrant virtual machine:
-   * add port forwarding to your Vagrantfile, e.g. `config.vm.network "forwarded_port", guest: 8000, host: 8000`
+    * add port forwarding to your Vagrantfile, e.g. `config.vm.network "forwarded_port", guest: 8000, host: 8000`
-   * use `mkdocs serve --dev-addr 0.0.0.0:8000` because the default localhost
+    * use `mkdocs serve --dev-addr 0.0.0.0:8000` because the default localhost
-      IP does not get forwarded.
+       IP does not get forwarded.

docs/develop/Postcodes.md

@@ -0,0 +1,40 @@
+# Postcodes in Nominatim
+
+The blog post [Nominatim and Postcodes](https://www.openstreetmap.org/user/lonvia/diary/43143)
+describes the new handling in Nominatim 3.1.
+
+Postcode centroids (aka 'calculated postcodes') are generated by looking at all postcodes of
+a country, grouping them and calculating the geometric centroid. There is currently no logic
+to deal with extreme outliers (typos or other mistakes in OSM data). There is also no check
+if a postcodes adhere's to a countries format, e.g. if Swiss postcodes are 4 digits.
+
+
+## Regular updating calculated postcodes
+
+The script to rerun the calculation is `build/utils/update.php --calculate-postcodes` and
+runs once per night on nominatim.openstreetmap.org.
+
+
+## Finding places that share a specific postcode
+
+In the Nominatim database run
+
+```sql
+  SELECT osm_type, osm_id, class, type, st_x(centroid) as lon, st_y(centroid) at lat
+  FROM placex 
+  WHERE country_code='fr'
+    AND upper(trim (both ' ' from address->'postcode')) = '33210';
+```
+
+Alternatively on [Overpass](https://overpass-turbo.eu/) run the following query
+
+```
+[out:json][timeout:250];
+area["name"="France"]->.boundaryarea;
+(
+nwr(area.boundaryarea)["addr:postcode"="33210"];
+);
+out body;
+>;
+out skel qt;
+```

docs/mkdocs.yml

@@ -22,6 +22,7 @@ pages:
         - 'Overview' : 'develop/overview.md'
         - 'OSM Data Import' : 'develop/Import.md'
         - 'Place Ranking' : 'develop/Ranking.md'
+        - 'Postcodes' : 'develop/Postcodes.md'
         - 'Documentation' : 'develop/Documentation.md'
     - 'External Data Sources':
         - 'Overview' : 'data-sources/overview.md'