Documentation
Reference
2.1.55 (current version)
collection
interactivityModel
Interfaces

Regions

In this section

General information

Sometimes you need to highlight a country or region on the map. To avoid manually creating each object that describes the desired geographical area, you can use the “Regions” module.

The “Regions” module allows you to instantly add entire regions to the map. In addition, you can work with them like separate objects: set the fill color and outline color, define object behavior when moused on, and so on.

“Regions” provide access to information about regional divisions of countries, including coordinates of borders and the names of units of administrative division.

Attention! The "Regions" module was created using data from “©OpenStreetMap Participants” and is distributed under the conditions of the license published on the site http://www.openstreetmap.org/copyright.

Information about regions is currently available for the following countries:

  • Russia
  • Ukraine
  • Kazakhstan
  • Belarus
  • Turkey

The module also allows you to mark all the countries of the world on the map.

How to add regions to the map

The regions.load function is available for downloading data about regions of a country. For parameters, specify the country code (for instance, 'RU'), along with any additional options as necessary:

  • lang — The language for displaying region names. Specified in ISO 639-1 format. By default, it takes the value set in the lang parameter when the API was enabled. The following languages are currently available:
    • For Russia: Russian, English
    • For Ukraine: Russian, Ukrainian, English
    • For Kazakhstan: Russian, English
    • For Belarus: Russian, Belarusian, English
    • For Turkey: Russian, Turkish, English
    • For all world countries: all languages
  • quality — The level of detail. Accepts a value from 0 to 3. The higher the level, the more precise the display of regional borders. By default, it takes the value “1”.
    quality = 0quality = 3

    The difference between levels of details is only visible at large scales. When the detail level is higher, the volume of downloaded data is greater, which increases the load on the browser. For this reason, we do not recommend using high detail for small-scale maps (for example, for an overview map).

When the regions.Load function gets data from OSM, it processes it and converts it to a GeoObjectCollection, which can then be added to the map. The link to this collection is located in the geoObjects field of the object passed to the callback function:

ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = result.geoObjects; // link to GeoObjectCollection
    myMap.geoObjects.add(regions);
}, function () {
    alert('No response');
});
Note. The sandbox provides a detailed example of working with regions.

The GeoObjectCollection is a container for the GeoObject objects that contain descriptions of all the country's regions. The description of each region includes its geometry, properties, and options.

The region's geometry is set in the geometry field and is identified by the geometric type and coordinates.

The properties specify metainformation about the region that was obtained from OSM. The region properties are set in the properties field and accessible using the following keys:

  • osmId — Region ID in OSM.
  • hintContent — Content of the pop-up hint that will appear when the mouse is pointed at the region. By default, it displays the region name.
  • name — Name of the region in the language specified in the lang parameter.

Options control the visual representation of the region on the map (the fill color, transparency, and so on). They are accessible via the options field.

Note. The API implements hierarchical inheritance for options. This means that if options are not set directly for a region, the API will search for them higher in the hierarchy, up to the map level.

Working with separate regions

To get access to the description of a certain region, use geoquery or the each method to go through all the elements of the collection and select the desired region. The example below shows how the Irkutsk region is selected from all regions of Russia, and a red fill color is set for it:

// 1 method: using geoquery.
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = ymaps.geoquery(result.geoObjects);
    regions.search('properties.osmId = 145454').setOptions('fillColor', '#ff001a');
    regions.addToMap(myMap);
    });
 }, function () {
    ...
});

// 1 method: pass through the array using the 'each' method.
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    var regions = result.geoObjects;
    // Enabling dragging for regions.
    regions.options.set('draggable', true);
    // Passing through the collection of regions and searching for the Irkutsk region (osmId = 145454).
    regions.each(function (reg) {
        if (reg.properties.get('osmId') == 145454) {
            // Changing the color to red
            reg.options.set('fillColor', '#ff001a')
        }
    });
    // Adding regions to the map
    myMap.geoObjects.add(regions); 
 }, function () {
    ...
});

The most practical way to search for a region is by its ID. The developer should first determine the ID of the desired region. The easiest way to do this is shown below:

// When clicking on a region, its ID is shown. 
ymaps.regions.load('RU', {
    lang: 'ru',
    quality: 1
}).then(function (result) {
    result.geoObjects.events.add('click', function (e) {
        var region = e.get('target');
        console.log(region.properties.get('name') + ' -> ' + region.properties.get('osmId'));
    });
    ...
}, function () {
    ...
});

To avoid defining IDs separately for every region, you can get the GeoObjectCollection once and create a hash based on it that contains the region names and corresponding IDs. As a result, you will be able to get the number of a desired region by accessing the created hash.

Example: adding the list of regions to the DOM tree

The example below shows how to add the list of regions that was downloaded using regions.load to the DOM tree. When a region is clicked, the map is centered on it and the fill color changes to pink. The example also shows how to hide the remaining part of the map that does not have regions added to it.

Open example in a new window

regions
adding regions to the map
working with regions
examples