docs/customize/Country-Settings.md

   1 # Customizing Per-Country Data
   2
   3 Whenever an OSM is imported into Nominatim, the object is first assigned
   4 a country. Nominatim can use this information to adapt various aspects of
   5 the address computation to the local customs of the country. This section
   6 explains how country assignment works and the principal per-country
   7 localizations.
   8
   9 ## Country assignment
  10
  11 Countries are assigned on the basis of country data from the OpenStreetMap
  12 input data itself. Countries are expected to be tagged according to the
  13 [administrative boundary schema](https://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative):
  14 a OSM relation with `boundary=administrative` and `admin_level=2`. Nominatim
  15 uses the country code to distinguish the countries.
  16
  17 If there is no country data available for a point, then Nominatim uses the
  18 fallback data imported from `data/country_osm_grid.sql.gz`. This was computed
  19 from OSM data as well but is guaranteed to cover all countries.
  20
  21 Some OSM objects may also be located outside any country, for example a buoy
  22 in the middle of the ocean. These object do not get any country assigned and
  23 get a default treatment when it comes to localized handling of data.
  24
  25 ## Per-country settings
  26
  27 ### Global country settings
  28
  29 The main place to configure settings per country is the file
  30 `settings/country_settings.yaml`. This file has one section per country that
  31 is recognised by Nominatim. Each section is tagged with the country code
  32 (in lower case) and contains the different localization information. Only
  33 countries which are listed in this file are taken into account for computations.
  34
  35 For example, the section for Andorra looks like this:
  36
  37 ```
  38     partition: 35
  39     languages: ca
  40     names: !include country-names/ad.yaml
  41     postcode:
  42       pattern: "(ddd)"
  43       output: AD\1
  44 ```
  45
  46 The individual settings are described below.
  47
  48 #### `partition`
  49
  50 Nominatim internally splits the data into multiple tables to improve
  51 performance. The partition number tells Nominatim into which table to put
  52 the country. This is purely internal management and has no effect on the
  53 output data.
  54
  55 The default is to have one partition per country.
  56
  57 #### `languages`
  58
  59 A comma-separated list of ISO-639 language codes of default languages in the
  60 country. These are the languages used in name tags without a language suffix.
  61 Note that this is not necessarily the same as the list of official languages
  62 in the country. There may be officially recognised languages in a country
  63 which are only ever used in name tags with the appropriate language suffixes.
  64 Conversely, a non-official language may appear a lot in the name tags, for
  65 example when used as an unofficial Lingua Franca.
  66
  67 List the languages in order of frequency of appearance with the most frequently
  68 used language first. It is not recommended to add languages when there are only
  69 very few occurrences.
  70
  71 If only one language is listed, then Nominatim will 'auto-complete' the
  72 language of names without an explicit language-suffix.
  73
  74 #### `names`
  75
  76 List of names of the country and its translations. These names are used as
  77 a baseline. It is always possible to search countries by the given names, no
  78 matter what other names are in the OSM data. They are also used as a fallback
  79 when a needed translation is not available.
  80
  81 !!! Note
  82     The list of names per country is currently fairly large because Nominatim
  83     supports translations in many languages per default. That is why the
  84     name lists have been separated out into extra files. You can find the
  85     name lists in the file `settings/country-names/<country code>.yaml`.
  86     The names section in the main country settings file only refers to these
  87     files via the special `!include` directive.
  88
  89 #### `postcode`
  90
  91 Describes the format of the postcode that is in use in the country.
  92
  93 When a country has no official postcodes, set this to no. Example:
  94
  95 ```
  96 ae:
  97     postcode: no
  98 ```
  99
 100 When a country has a postcode, you need to state the postcode pattern and
 101 the default output format. Example:
 102
 103 ```
 104 bm:
 105     postcode:
 106       pattern: "(ll)[ -]?(dd)"
 107       output: \1 \2
 108 ```
 109
 110 The **pattern** is a regular expression that describes the possible formats
 111 accepted as a postcode. The pattern follows the standard syntax for
 112 [regular expressions in Python](https://docs.python.org/3/library/re.html#regular-expression-syntax)
 113 with two extra shortcuts: `d` is a shortcut for a single digit([0-9])
 114 and `l` for a single ASCII letter ([A-Z]).
 115
 116 Use match groups to indicate groups in the postcode that may optionally be
 117 separated with a space or a hyphen.
 118
 119 For example, the postcode for Bermuda above always consists of two letters
 120 and two digits. They may optionally be separated by a space or hyphen. That
 121 means that Nominatim will consider `AB56`, `AB 56` and `AB-56` spelling variants
 122 for one and the same postcode.
 123
 124 Never add the country code in front of the postcode pattern. Nominatim will
 125 automatically accept variants with a country code prefix for all postcodes.
 126
 127 The **output** field is an optional field that describes what the canonical
 128 spelling of the postcode should be. The format is the
 129 [regular expression expand syntax](https://docs.python.org/3/library/re.html#re.Match.expand) referring back to the bracket groups in the pattern.
 130
 131 Most simple postcodes only have one spelling variant. In that case, the
 132 **output** can be omitted. The postcode will simply be used as is.
 133
 134 In the Bermuda example above, the canonical spelling would be to have a space
 135 between letters and digits.
 136
 137 !!! Warning
 138     When your postcode pattern covers multiple variants of the postcode, then
 139     you must explicitly state the canonical output or Nominatim will not
 140     handle the variations correctly.
 141
 142 ### Other country-specific configuration
 143
 144 There are some other configuration files where you can set localized settings
 145 according to the assigned country. These are:
 146
 147  * [Place ranking configuration](Ranking.md)
 148
 149 Please see the linked documentation sections for more information.