documentation: new page explaining calculated postcodes

[nominatim.git] / docs / develop / Postcodes.md

diff --git a/docs/develop/Postcodes.md b/docs/develop/Postcodes.md
new file mode 100644 (file)
index 0000000..8b53216
--- /dev/null
+++ b/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;
+```