update and document GB postcode data

data-sources/gb-postcodes/README.md

@@ -0,0 +1,49 @@
+# GB Postcodes
+
+
+The server [importing instructions](https://www.nominatim.org/release-docs/latest/admin/Import-and-Update/) allow optionally download [`gb_postcode_data.sql.gz`](https://www.nominatim.org/data/gb_postcode_data.sql.gz). This document explains how the file got created.
+
+## GB vs UK
+
+GB (Great Britain) is more correct as the Ordnance Survey dataset doesn't contain postcodes from Northern Ireland.
+
+## Importing separately after the initial import
+
+If you forgot to download the file, or have a new version, you can import it separately:
+
+1. Table schema is in `/data/gb_postcode_table.sql`. 
+
+2. Run `GRANT SELECT ON TABLE gb_postcode TO "{www-user}";` (found in file `sql/tables.sql`). `{www-user}` needs to be replaced with the user the webserver (e.g. Apache2) runs under, e.g. on Ubuntu that's `www-data`.
+
+3. Import the downloaded `gb_postcode_data.sql.gz` file.
+
+4. Run `utils/setup.php --calculate-postcodes` from the build directory. This will copy data form the `gb_postcode` table to the `location_postcodes` table.
+
+
+
+## Converting Code-Point Open data
+
+1. Download from [Code-Point® Open
+](https://www.ordnancesurvey.co.uk/business-and-government/products/code-point-open.html). It requires an email address where a download link will be send to.
+
+2. `unzip codepo_gb.zip`
+
+   Unpacked you'll see a directory of CSV files.
+
+   ```
+   $ more codepo_gb/Data/CSV/n.csv
+   "N1 0AA",10,530626,183961,"E92000001","E19000003","E18000007","","E09000019","E05000368"
+   "N1 0AB",10,530559,183978,"E92000001","E19000003","E18000007","","E09000019","E05000368"
+   ```
+
+   The coordinates are "Northings" and "Eastings" in [OSGB 1936](http://epsg.io/1314) projection. They can be projected to WGS84 like this
+
+   ```
+   SELECT ST_AsText(ST_Transform(ST_SetSRID('POINT(530626 183961)'::geometry,27700), 4326));
+   POINT(-0.117872733220225 51.5394424719303)
+   ```
+   [-0.117872733220225 51.5394424719303 on OSM map](https://www.openstreetmap.org/?mlon=-0.117872733220225&mlat=51.5394424719303&zoom=16)
+
+
+3. `cat codepo_gb/Data/CSV/*.csv | data-sources/gb-postcodes/convert_codepoint.php > gb_postcode_data.sql`
+

data-sources/gb-postcodes/convert_codepoint.php

@@ -0,0 +1,48 @@
+#!/usr/bin/php
+<?php
+
+echo <<< EOT
+
+-- This data contains Ordnance Survey data © Crown copyright and database right 2010.
+-- Code-Point Open contains Royal Mail data © Royal Mail copyright and database right 2010.
+-- OS data may be used under the terms of the OS OpenData licence:
+-- http://www.ordnancesurvey.co.uk/oswebsite/opendata/licence/docs/licence.pdf
+
+SET statement_timeout = 0;
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = off;
+SET check_function_bodies = false;
+SET client_min_messages = warning;
+
+CREATE TEMPORARY TABLE gb_postcode_tmp (
+    id integer,
+    postcode character varying(9),
+    easting bigint,
+    northing bigint
+);
+
+COPY gb_postcode_tmp (id, postcode, easting, northing) FROM stdin;
+
+EOT;
+
+$iCounter = 0;
+while ($sLine = fgets(STDIN)) {
+    $aColumns = str_getcsv($sLine);
+
+    // https://stackoverflow.com/questions/9144592/php-split-a-postcode-into-two-parts#comment11589150_9144834
+    // insert space before the third last position
+    $postcode = $aColumns[0];
+    $postcode = preg_replace('/\s*(...)$/', ' $1', $postcode);
+
+    echo join("\t", array($iCounter, $postcode, $aColumns[2], $aColumns[3]))."\n";
+
+    $iCounter = $iCounter + 1;
+}
+
+echo <<< EOT
+\.
+INSERT INTO gb_postcode
+SELECT id, postcode, ST_Transform(ST_SetSRID(CONCAT('POINT(', easting, ' ', northing, ')')::geometry, 27700), 4326) FROM gb_postcode_tmp;
+DROP TABLE gb_postcode_tmp;
+
+EOT;