Документация
Справочник JavaScript API
2.1.64 (текущая версия)
collection
interactivityModel
Интерфейсы

Регионы

Краткое содержание

Общие сведения

Иногда на карте требуется выделить какую-нибудь страну или регион. Чтобы вручную не создавать каждый объект, описывающий нужную географическую область, можно воспользоваться модулем «Регионы».

Модуль «Регионы» позволяет отметить на карте все страны мира. С географическими областями можно работать как с отдельными объектами: задавать цвет контура и заливки, обрабатывать события и т. п.

Модуль «Регионы» предоставляет информацию об административно-территориальном делении стран. Например, названия регионов, их границы и т. д. Информация о региональном делении доступна для стран: Россия, Украина, Казахстан, Белоруссия, Турция.

Как добавить регионы на карту

Примечание. Использование политики CSP влияет на работу с «Регионами». Для корректной работы модуля необходимо задать политику в директиве 'connect-src'. Подробнее см. в разделе Подключение API.

Для загрузки данных о регионах предназначена функция borders.load. В качестве аргумента функции необходимо передать код страны в формате ISO-3166. Допустимые значения: RU, UA, BY, KZ, TR, AQ, '001'. При указании значения '001' будут показаны границы стран мира (без административно-территориального деления).

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

Функция borders.load возвращает Promise, который будет разрешен GeoJSON-объектом с информацией о регионах (см. описание GeoJSON-объекта).

Отобразить регионы на карте можно несколькоми способами: через geoQuery, ObjectManager и GeoObject. Ниже рассмотрены примеры.

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();
  // Чтобы добавить объекты в ObjectManager, необходимо
  // задать для них идентификаторы.
  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);
  }
});

Параметры отображения регионов

Функции borders.load() можно задать параметры отображения регионов:

  • lang — язык, на котором будут отображены названия регионов. Указывается в формате ISO 639-1. По умолчанию принимает значение, указанное в параметре lang при подключении API.
  • disputedBorders — код страны в формате ISO-3166. Параметр определяет страну, с точки зрения которой нужно отобразить cпорные границы. Допустимые значения: RU, UA, UN (разделение границ с точки зрения России, Украины и ООН соответственно). По умолчанию совпадает с кодом страны, который указан при загрузке API.
  • quality — уровень детализации. Может принимать значение от 0 до 3. Чем выше уровень, тем выше точность отображения региональных границ. По умолчанию принимает значение «1».
    quality = 0quality = 3

    Разница между уровнями детализации видна только на крупных масштабах. При повышении уровня детализации увеличивается объем загружаемых данных и, как следствие, возрастает нагрузка на браузер. Поэтому не рекомендуется использовать высокую детализацию для мелкомасштабных карт (например, для обзорной карты).

    ymaps.borders.load('RU', {
      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);
      }
    });

Описание GeoJSON-объекта

Ниже приведена структура GeoJSON-объекта, содержащего информацию о странах и регионах:
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry
[no-highlight[

Геометрия границ страны или региона. Описывается типом геометрии и координатами.

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

Тип геометрии. Возможные значения: «Polygon».

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

Координаты границ страны или региона.

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

Строковый идентификатор, определяющий алгоритм заливки многоугольника. Подробнее см. в справочнике в описании класса geometry.Polygon.

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

Информация об административной единице.

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

Название административной единицы. Указывается на том языке, который задан в параметре lang.

]no-highlight]
": "Алтайский край", "hintContent
[no-highlight[

Содержимое всплывающей подсказки, которая будет появляться при наведении курсора на регион. По умолчанию отображается его название.

]no-highlight]
": "Алтайский край", "iso3166
[no-highlight[

Код региона в формате ISO-3166. Например, «RU-MOS».

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

Порядок региона в иерархии административно-территориального деления. Например, для страны порядок равен 2.

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

Массив родительских объектов, которым принадлежит регион. Например, для Ямало-Ненецкого автономного округа родительскими объектами являются Тюменская область и Россия.

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

Разница между порядком региона и его родительской территории.

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

ISO-код родительского объекта.

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

Геометрия границ страны или региона. Описывается типом геометрии и координатами.

properties

Информация об административной единице.

geometry
type

Тип геометрии. Возможные значения: «Polygon».

coordinates

Координаты границ страны или региона.

fillRule

Строковый идентификатор, определяющий алгоритм заливки многоугольника. Подробнее см. в справочнике в описании класса geometry.Polygon.

properties
name

Название административной единицы. Указывается на том языке, который задан в параметре lang.

hintContent

Содержимое всплывающей подсказки, которая будет появляться при наведении курсора на регион. По умолчанию отображается его название.

iso3166

Код региона в формате ISO-3166. Например, «RU-MOS».

level

Порядок региона в иерархии административно-территориального деления. Например, для страны порядок равен 2.

parents

Массив родительских объектов, которым принадлежит регион. Например, для Ямало-Ненецкого автономного округа родительскими объектами являются Тюменская область и Россия.

delta

Разница между порядком региона и его родительской территории.

iso3166

ISO-код родительского объекта.

Поиск по регионам

Осуществлять поиск по регионам целесообразно по их идентификаторам. В качестве идентификаторов можно использовать ISO-коды регионов. Ниже рассмотрен пример, в котором из всех регионов России выбирается Иркутская область и для нее задается красный цвет заливки:

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

регионы
добавление регонов на карту
работа с регионами
примеры
показать страны на карте