5.8 KiB
Customizing Per-Country Data
Whenever an OSM is imported into Nominatim, the object is first assigned a country. Nominatim can use this information to adapt various aspects of the address computation to the local customs of the country. This section explains how country assignment works and the principal per-country localizations.
Country assignment
Countries are assigned on the basis of country data from the OpenStreetMap
input data itself. Countries are expected to be tagged according to the
administrative boundary schema:
a OSM relation with boundary=administrative and admin_level=2. Nominatim
uses the country code to distinguish the countries.
If there is no country data available for a point, then Nominatim uses the
fallback data imported from data/country_osm_grid.sql.gz. This was computed
from OSM data as well but is guaranteed to cover all countries.
Some OSM objects may also be located outside any country, for example a buoy in the middle of the ocean. These object do not get any country assigned and get a default treatment when it comes to localized handling of data.
Per-country settings
Global country settings
The main place to configure settings per country is the file
settings/country_settings.yaml. This file has one section per country that
is recognised by Nominatim. Each section is tagged with the country code
(in lower case) and contains the different localization information. Only
countries which are listed in this file are taken into account for computations.
For example, the section for Andorra looks like this:
partition: 35
languages: ca
names: !include country-names/ad.yaml
postcode:
pattern: "(ddd)"
output: AD\1
The individual settings are described below.
partition
Nominatim internally splits the data into multiple tables to improve performance. The partition number tells Nominatim into which table to put the country. This is purely internal management and has no effect on the output data.
The default is to have one partition per country.
languages
A comma-separated list of ISO-639 language codes of default languages in the country. These are the languages used in name tags without a language suffix. Note that this is not necessarily the same as the list of official languages in the country. There may be officially recognised languages in a country which are only ever used in name tags with the appropriate language suffixes. Conversely, a non-official language may appear a lot in the name tags, for example when used as an unofficial Lingua Franca.
List the languages in order of frequency of appearance with the most frequently used language first. It is not recommended to add languages when there are only very few occurrences.
If only one language is listed, then Nominatim will 'auto-complete' the language of names without an explicit language-suffix.
names
List of names of the country and its translations. These names are used as a baseline. It is always possible to search countries by the given names, no matter what other names are in the OSM data. They are also used as a fallback when a needed translation is not available.
!!! Note
The list of names per country is currently fairly large because Nominatim
supports translations in many languages per default. That is why the
name lists have been separated out into extra files. You can find the
name lists in the file settings/country-names/<country code>.yaml.
The names section in the main country settings file only refers to these
files via the special !include directive.
postcode
Describes the format of the postcode that is in use in the country.
When a country has no official postcodes, set this to no. Example:
ae:
postcode: no
When a country has a postcode, you need to state the postcode pattern and the default output format. Example:
bm:
postcode:
pattern: "(ll)[ -]?(dd)"
output: \1 \2
The pattern is a regular expression that describes the possible formats
accepted as a postcode. The pattern follows the standard syntax for
regular expressions in Python
with two extra shortcuts: d is a shortcut for a single digit([0-9])
and l for a single ASCII letter ([A-Z]).
Use match groups to indicate groups in the postcode that may optionally be separated with a space or a hyphen.
For example, the postcode for Bermuda above always consists of two letters
and two digits. They may optionally be separated by a space or hyphen. That
means that Nominatim will consider AB56, AB 56 and AB-56 spelling variants
for one and the same postcode.
Never add the country code in front of the postcode pattern. Nominatim will automatically accept variants with a country code prefix for all postcodes.
The output field is an optional field that describes what the canonical spelling of the postcode should be. The format is the regular expression expand syntax referring back to the bracket groups in the pattern.
Most simple postcodes only have one spelling variant. In that case, the output can be omitted. The postcode will simply be used as is.
In the Bermuda example above, the canonical spelling would be to have a space between letters and digits.
!!! Warning When your postcode pattern covers multiple variants of the postcode, then you must explicitly state the canonical output or Nominatim will not handle the variations correctly.
Other country-specific configuration
There are some other configuration files where you can set localized settings according to the assigned country. These are:
Please see the linked documentation sections for more information.