Documentation
Reference
2.1.64 (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 a geographical area, you can use the “Regions” module.

The “Regions” module lets you mark all the countries of the world on the map. You can work with geographical areas the same way as with separate objects: set the outline color and fill color, handle events, and so on.

The “Regions” module provides information about territorial divisions within countries, including the names of regions, their borders, and so on. Information about regional divisions is available for the countries: Russia, Ukraine, Kazakhstan, Belarusia, and Turkey.

How to add regions to the map

Note. Using a CSP policy affects interaction with “Regions”. For the module to work correctly, you must set the policy in the 'connect-src' directive. For more information, see Enabling the API.

Use the borders.load function for loading data about regions. Pass the country code in ISO-3166 format as an argument of the function. Accepted values: RU, UA, BY, KZ, TR, AQ, '001'. When the value is '001', the borders of all countries are shown (without internal regional divisions).

ymaps.borders.load('EN').then(function (geojson) {
   console.log(geojson);
}, function (e) {
   console.log(e);
});

The borders.load function returns a Promise that will be resolved by a GeoJSON object with information about regions (see the description of the GeoJSON object).

There are several ways to display regions on the map: using geoQuery, ObjectManager, and GeoObject. Examples are shown below.

ymaps.borders.load('001').then(function (geojson) {
  var regions = ymaps.geoQuery(geojson);
  regions.addToMap(myMap);
});
ymaps.borders.load('001').then(function (geojson) {
  var objectManager = new ymaps.ObjectManager();
  // To add objects to the ObjectManager, you must
  // set IDs for them.
  var features = geojson.features.map(function (feature) {
        feature.id = feature.properties.iso3166;
        return feature;
      }); 
  objectManager.add(features);
  myMap.geoObjects.add(objectManager);
}, function (e) {
   console.log(e);
});
ymaps.borders.load('001').then(function (geojson) {
  for (var i = 0; i < geojson.features.length; i++) {
    var geoObject = new ymaps.GeoObject(geojson.features[i]);
    myMap.geoObjects.add(geoObject);
  }
});

Parameters for displaying regions

You can set the region display parameters for the borders.load() function:

  • 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.
  • disputedBorders — Country code in ISO-3166 format. This parameter determines the country to use as the reference for showing disputed borders. Accepted values: RU, UA, UN (show borders according to Russia, Ukraine, or the United Nations, respectively). By default, it is the same as the country code that is specified when loading the API.
  • 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).

    ymaps.borders.load('001', {
      lang: "en",
      quality: 2
    }).then(function (geojson) {
      for (var i = 0; i < geojson.features.length; i++) {
        var geoObject = new ymaps.GeoObject(geojson.features[i]);
        myMap.geoObjects.add(geoObject);
      }
    });

Description of the GeoJSON object

The structure of a GeoJSON object, which contains information about countries and regions:
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry
[no-highlight[

Geometry of the borders of a country or region. Defined by the geometry type and coordinates.

]no-highlight]
": { "type
[no-highlight[

Geometry type. Possible values: “Polygon”.

]no-highlight]
": "Polygon", "coordinates
[no-highlight[

Coordinates of the borders of a country or region.

]no-highlight]
": [ [53.290675, 77.9073936092012], [53.3671486, 77.889309], ... ], "fillRule
[no-highlight[

String ID that defines the polygon fill rule. For more information, see the description of the geometry.Polygon class in the reference guide.

]no-highlight]
": "evenOdd" }, "properties
[no-highlight[

Information about a regional division.

]no-highlight]
": { "name
[no-highlight[

Name of the regional division. Shown in the lang that is set in the lang parameter.

]no-highlight]
": "Altai region", "hintContent
[no-highlight[

Content of the pop-up hint that will appear when the mouse is pointed at the region. By default, it displays the name.

]no-highlight]
": "Altai region", "iso3166
[no-highlight[

Code of the region in ISO-3166 format. For example, “RU-MOS”.

]no-highlight]
": "RU-ALT", "level
[no-highlight[

The region‘s level in the hierarchy of territorial divisions. For example, for a country, the level is 2.

]no-highlight]
": 4, "parents
[no-highlight[

Array of parent objects that the region belongs to. For example, for the Yamalo-Nenetsky district, the parent objects are the Tyumen region and Russia.

]no-highlight]
": [ { "delta
[no-highlight[

The difference between the region‘s level and its parent territory.

]no-highlight]
": -2, "iso3166
[no-highlight[

ISO code of the parent object.

]no-highlight]
": "RU" } ] } } } ] }
feature
geometry

Geometry of the borders of a country or region. Defined by the geometry type and coordinates.

properties

Information about a regional division.

geometry
type

Geometry type. Possible values: “Polygon”.

coordinates

Coordinates of the borders of a country or region.

fillRule

String ID that defines the polygon fill rule. For more information, see the description of the geometry.Polygon class in the reference guide.

properties
name

Name of the regional division. Shown in the lang that is set in the lang parameter.

hintContent

Content of the pop-up hint that will appear when the mouse is pointed at the region. By default, it displays the name.

iso3166

Code of the region in ISO-3166 format. For example, “RU-MOS”.

level

The region's level in the hierarchy of territorial divisions. For example, for a country, the level is 2.

parents

Array of parent objects that the region belongs to. For example, for the Yamalo-Nenetsky district, the parent objects are the Tyumen region and Russia.

delta

The difference between the region's level and its parent territory.

iso3166

ISO code of the parent object.

Search for regions

The most practical way to search for regions is by their IDs. The ISO codes of regions can be used as the IDs. The example below shows how the Irkutsk region is selected from all regions of Russia, and a red fill color is set for it:

ymaps.borders.load('RU', {
  lang: 'en',
  quality: 1
}).then(function (geojson) {
  var regions = ymaps.geoQuery(geojson);
  regions.search('properties.iso3166 = "RU-IRK"').setOptions('fillColor', '#ff001a');
  regions.addToMap(myMap);
});

regions
adding regions to the map
working with regions
examples
show countries on the map