data-sources/country-grid/README.md

   1 # Fallback Country Boundaries
   2
   3 Each place is assigned a `country_code` and partition. Partitions derive from `country_code`.
   4
   5 Nominatim imports two pre-generated files
   6
   7    * `data/country_name.sql` (country code, name, default language, partition)
   8    * `data/country_osm_grid.sql` (country code, geometry)
   9
  10 before creating places in the database. This helps with fast lookups and missing data (e.g. if the data the user wants to import doesn't contain any country places).
  11
  12 The number of countries in the world can change (South Sudan created 2011, Germany reunification), so can their boundaries. This document explain how the pre-generated files can be updated.
  13
  14
  15
  16 ## Country code
  17
  18 Each place is assigned a two letter country_code based on its location, e.g. `gb` for Great Britain. Or `NULL` if no suitable country is found (usually it's in open water then).
  19
  20 In `sql/functions.sql: get_country_code(geometry)` the place's center is checked against
  21
  22    1. country places already imported from the user's data file. Places are imported by rank low-to-high. Lowest rank 2 is countries so most places should be matched. Still the data file might be incomplete.
  23    2. if unmatched: OSM grid boundaries
  24    3. if still unmatched: OSM grid boundaries, but allow a small distance
  25
  26
  27
  28 ## Partitions
  29
  30 Each place is assigned partition, which is a number 0..250. 0 is fallback/other.
  31
  32 During place indexing (`sql/functions.sql: placex_insert()`) a place is assigned the partition based on its country code (`sql/functions.sql: get_partition(country_code)`). It checks in the `country_name` table.
  33
  34 Most countries have their own parition, some share a partition. Thus partition counts vary greatly.
  35
  36 Several database tables are split by partition to allow queries to run against less indices and improve caching.
  37
  38    * `location_area_large_<partition>`
  39    * `search_name_<partition>`
  40    * `location_road_<partition>`
  41
  42
  43
  44
  45
  46 ## Data files
  47
  48 ### `data/country_name.sql`
  49
  50 Export from existing database table plus manual changes. `country_default_language_code` most taken from [https://wiki.openstreetmap.org/wiki/Nominatim/Country_Codes](), see `utils/country_languages.php`.
  51
  52
  53
  54 ### `data/country_osm_grid.sql`
  55
  56 `country_grid.sql` merges territories by country. Then uses `function.sql: quad_split_geometry` to split each country into multiple [Quadtree](https://en.wikipedia.org/wiki/Quadtree) polygons for faster point-in-polygon lookups.
  57
  58 To visualize one country as geojson feature collection, e.g. for loading into [geojson.io](http://geojson.io/):
  59
  60 ```
  61 -- http://www.postgresonline.com/journal/archives/267-Creating-GeoJSON-Feature-Collections-with-JSON-and-PostGIS-functions.html
  62
  63 SELECT row_to_json(fc)
  64 FROM (
  65   SELECT 'FeatureCollection' As type, array_to_json(array_agg(f)) As features
  66   FROM (
  67     SELECT 'Feature' As type,
  68     ST_AsGeoJSON(lg.geometry)::json As geometry,
  69     row_to_json((country_code, area)) As properties
  70     FROM country_osm_grid As lg where country_code='mx'
  71   ) As f
  72 ) As fc;
  73 ```
  74
  75 `cat /tmp/query.sql | psql -At nominatim > /tmp/mexico.quad.geojson`
  76
  77 ![mexico](mexico.quad.png)