Регионы

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

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

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

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

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

Примечание. Использование политики 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);
});

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

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

  • lang — язык, на котором будут отображены названия регионов. Указывается в формате ISO 639-1. По умолчанию принимает значение, указанное в параметре lang при подключении API.
  • disputedBorders — код страны в формате ISO-3166. Параметр определяет страну, с точки зрения которой нужно отобразить cпорные границы. Допустимые значения: RU, UA, UN (разделение границ с точки зрения России, Украины и ООН соответственно). По умолчанию совпадает с кодом страны, который указан при загрузке API.
  • quality — уровень детализации. Может принимать значение от 0 до 3. Чем выше уровень, тем выше точность отображения региональных границ. По умолчанию принимает значение «1».
    quality = 0 quality = 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": {
          "type": "Polygon",
          "coordinates": [
            [53.290675, 77.9073936092012],
            [53.3671486, 77.889309],
            ...   
          ],
          "fillRule": "evenOdd"
      },
      "properties": {
          "name": "Алтайский край",
          "hintContent": "Алтайский край",
          "iso3166": "RU-ALT",
          "neighbors": [
              "RU-NVS",
              "RU-KEM",
              "RU-AL"
          ],
          "level": 4,
          "parents": [
            {
              "delta": -2,
              "iso3166": "RU"
            }
          ]
        }
      }
    }
  ]
}
feature
geometry

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

properties

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

geometry
type

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

coordinates

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

fillRule

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

properties
name

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

hintContent

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

iso3166

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

neighbors

Соседи региона. Соседними считаются регионы со смежными границами.

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);
});

Открыть пример в песочнице