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) {
}, function (e) {
Copied to clipboard

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);
Copied to clipboard

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 = 0 quality = 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]);
    Copied to clipboard

Description of the GeoJSON object

The structure of a GeoJSON object, which contains information about countries and regions:
  "type": "FeatureCollection",
  "features": [
      "type": "Feature",
      "geometry": {
          "type": "Polygon",
          "coordinates": [
            [53.290675, 77.9073936092012],
            [53.3671486, 77.889309],
          "fillRule": "evenOdd"
      "properties": {
          "name": "Altai region",
          "hintContent": "Altai region",
          "iso3166": "RU-ALT",
          "level": 4,
          "parents": [
              "delta": -2,
              "iso3166": "RU"
Copied to clipboard

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


Information about a regional division.


Geometry type. Possible values: “Polygon”.


Coordinates of the borders of a country or region.


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


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


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


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


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


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.


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


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);'properties.iso3166 = "RU-IRK"').setOptions('fillColor', '#ff001a');
Copied to clipboard