docs/develop/Import.md

   1 # OSM Data Import
   2
   3 OSM data is initially imported using osm2pgsql. Nominatim uses its own data
   4 output style 'gazetteer', which differs from the output style created for
   5 map rendering.
   6
   7 ## Database Layout
   8
   9 The gazetteer style produces a single table `place` with the following rows:
  10
  11  * `osm_type` - kind of OSM object (**N** - node, **W** - way, **R** - relation)
  12  * `osm_id` - original OSM ID
  13  * `class` - key of principal tag defining the object type
  14  * `type` - value of principal tag defining the object type
  15  * `name` - collection of tags that contain a name or reference
  16  * `admin_level` - numerical value of the tagged administrative level
  17  * `address` - collection of tags defining the address of an object
  18  * `extratags` - collection of additional interesting tags that are not
  19                  directly relevant for searching
  20  * `geometry` - geometry of the object (in WGS84)
  21
  22 A single OSM object may appear multiple times in this table when it is tagged
  23 with multiple tags that may constitute a principal tag. Take for example a
  24 motorway bridge. In OSM, this would be a way which is tagged with
  25 `highway=motorway` and `bridge=yes`. This way would appear in the `place` table
  26 once with `class` of `highway` and once with a `class` of `bridge`. Thus the
  27 *uique key* for `place` is (`osm_type`, `osm_id`, `class`).
  28
  29 ## Configuring the Import
  30
  31 How tags are interpreted and assigned to the different `place` columns can be
  32 configured via the import style configuration file (`CONST_Import_style`). This
  33 is a JSON file which contains a list of rules which are matched against every
  34 tag of every object and then assign the tag its specific role.
  35
  36 ### Configuration Rules
  37
  38 A single rule looks like this:
  39
  40 ```json
  41 {
  42     "keys" : ["key1", "key2", ...],
  43     "values" : {
  44         "value1" : "prop",
  45         "value2" : "prop1,prop2"
  46     }
  47 }
  48 ```
  49
  50 A rule first defines a list of keys to apply the rule to. This is always a list
  51 of strings. The string may have four forms. An empty string matches against
  52 any key. A string that ends in an asterisk `*` is a prefix match and accordingly
  53 matches against any key that starts with the given string (minus the `*`). A
  54 suffix match can be defined similarly with a string that starts with a `*`. Any
  55 other string constitutes an exact match.
  56
  57 The second part of the rules defines a list of values and the properties that
  58 apply to a successful match. Value strings may be either empty, which again
  59 means that thy match against any value, or describe an exact match. Prefix
  60 or suffix matching of values is not possible.
  61
  62 For a rule to match, it has to find a valid combination of keys and values. The
  63 resulting property is that of the matched values.
  64
  65 The rules in a configuration file are processed sequentially and the first
  66 match for each tag wins.
  67
  68 A rule where key and value are the empty string is special. This defines the
  69 fallback when none of the rules matches. The fallback is always used as a last
  70 resort when nothing else matches, no matter where the rule appears in the file.
  71 Defining multiple fallback rules is not allowed. What happens in this case,
  72 is undefined.
  73
  74 ### Tag Properties
  75
  76 One or more of the following properties may be given for each tag:
  77
  78 * `main`
  79
  80     A principal tag. A new row will be added for the object with key and value
  81     as `class` and `type`.
  82
  83 * `with_name`
  84
  85     When the tag is a principal tag (`main` property set): only really add a new
  86     row, if there is any name tag found (a reference tag is not sufficient, see
  87     below).
  88
  89 * `with_name_key`
  90
  91     When the tag is a principal tag (`main` property set): only really add a new
  92     row, if there is also a name tag that matches the key of the principal tag.
  93     For example, if the main tag is `bridge=yes`, then it will only be added as
  94     an extra row, if there is a tag `bridge:name[:XXX]` for the same object.
  95     If this property is set, all other names that are not domain-specific are
  96     ignored.
  97
  98 * `fallback`
  99
 100     When the tag is a principal tag (`main` property set): only really add a new
 101     row, when no other principal tags for this object have been found. Only one
 102     fallback tag can win for an object.
 103
 104 * `operator`
 105
 106     When the tag is a principal tag (`main` property set): also include the
 107     `operator` tag in the list of names. This is a special construct for an
 108     out-dated tagging practise in OSM. Fuel stations and chain restaurants
 109     in particular used to have the name of the chain tagged as `operator`.
 110     These days the chain can be more commonly found in the `brand` tag but
 111     there is still enough old data around to warrant this special case.
 112
 113 * `name`
 114
 115     Add tag to the list of names.
 116
 117 * `ref`
 118
 119     Add tag to the list of names as a reference. At the moment this only means
 120     that the object is not considered to be named for `with_name`.
 121
 122 * `address`
 123
 124     At tag to the list of address tags. If the tag starts with `addr:` or
 125     `is_in:`, then this prefix is cut off before adding it to the list.
 126
 127 * `postcode`
 128
 129     At the value as a postcode to the address tags. If multiple tags are
 130     candidate for postcodes, one wins out and the others are dropped.
 131
 132 * `country`
 133
 134     At the value as a country code to the address tags. The value must be a
 135     two letter country code, otherwise it is ignored. If there are multiple
 136     tags that match, then one wins out and the others are dropped.
 137
 138 * `house`
 139
 140     If no principle tags can be found for the object, still add the object with
 141     `class`=`place` and `type`=`house`. Use this for address nodes that have no
 142     other function.
 143
 144 * `interpolation`
 145
 146     Add this object as an address interpolation (appears as `class`=`place` and
 147     `type`=`houses` in the database).
 148
 149 * `extra`
 150
 151     Add tag to the list of extra tags.
 152
 153 * `skip`
 154
 155     Skip the tag completely. Useful when a custom default fallback is defined
 156     or to define exceptions to rules.
 157
 158 A rule can define as many of these properties for one match as it likes. For
 159 example, if the property is `"main,extra"` then the tag will open a new row
 160 but also have the tag appear in the list of extra tags.
 161
 162 There are a number of pre-defined styles in the `settings/` directory. It is
 163 advisable to start from one of these styles when defining your own.
 164
 165 ### Changing the Style of Existing Databases
 166
 167 There is normally no issue changing the style of a database that is already
 168 imported and now kept up-to-date with change files. Just be aware that any
 169 change in the style applies to updates only. If you want to change the data
 170 that is already in the database, then a reimport is necessary.