Программные интерфейсы геопортала. API - версия 4.0

Пользователи могут размещать карты и отдельные слои пространственных данных геопортала ИВМ СО РАН на своих веб-страницах. Для этого нужно использовать программные интерфейсы (API) геопортала.
С технической точки зрения API геопортала - это набор JavaScript-компонентов для создания интерактивных карт.

Ниже представлен рабочий пример: 

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">

    <title>Карта</title>

    <style>
        #map {
            width: 600px;
            height: 400px;
        }
    </style>

    <script type="text/javascript" src="http://gis.krasn.ru/maps/api/map.4.0.js"></script>

    <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Element.prototype.classList"></script>

    <script type="text/javascript">
        var map = null;
        window.onload = function() {
            map = new kuboMap.Map('map', {}, {}, { x: 194723, y: -3421722, zoom: 2, tile: 'base' });
        }
    </script>
</head>

<body>
    <div id="map"></div>
</body>
</html>

Подключение библиотеки

Для подключения библиотеки добавьте следующую строку на Вашу страницу: 

<script type="text/javascript" src="http://gis.krasn.ru/maps/api/map.4.0.js"></script>

Для поддержки работы браузера Internet Explorer 11 необходимо добавить следующие строки: 

<script type="text/javascript" src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Element.prototype.classList"></script>

Для работы библиотеки в Internet Explorer 11 требуется свойство classList. Подробности https://developer.mozilla.org/en-US/docs/Web/API/Element/classList.


Добавление карты

Создание карты на странице

Основным объектом библиотеки является карта. Чтобы добавить карту на страницу, нужно добавить div-контейнер карты на страницу и использовать метод kuboMap.Map после полной загрузки страницы: 

map = new kuboMap.Map(<map>, <options>, <config>, <init view>);

Доступны следующие настройки:

map - элемент страницы для карты (string/HTMLElement);
options - настройки карты (object);
config - настройки ресурса (object);
init view - начальные настройки видимости карты (object).

Например: 

<div id="map" style="width: 100%; height: 100%;"></div>

<script type="text/javascript">
    var map = null;
    window.onload = function() {
        map = new kuboMap.Map('map', {}, { id: 'code' }, {});
    }
</script>

В качестве первого параметра необходимо указать div-контейнер с картой или его название на Вашей странице. Два следующих параметра обязательны (могут быть пустыми) и задают дополнительные настройки внешнего вида карты и настройки ресурса геопортала. Последний параметр задает стартовую позицию и масштаб карты.

Размеры элемента страницы с картой задаются через стили, например: 

#map {
    width: 100%;
    height: 100%;
    border: solid 1px #000;
}

Добавление элементов управления

Для добавления элементов управления и навигации на страницу необходимо определить их в настройках карты, например: 

var mapOptions = {
    mousePosition: true,
    scaleLine: false,
    zoomBar: false,
    query: true,
    measure: false
};
map = new kuboMap.Map('map', mapOptions, mapConfig, {});

Доступны следуюшие настройки карты:

mousePosition: позиция указателя, отображает текущее положение курсора на карте;
scaleLine: масштабная линейка, позволяет оценивать расстояние между объектами, не прибегая к вычислениям;
scale: числовое значение масштаба, позволяет оценивать расстояние между объектами, не прибегая к вычислениям;
zoomBar: масштабирование (кнопки + и -);
query: включает и выключает вывод информации при клике на карте (для добавлении кнопки запрос по области нужно включать эту настройку);
queryType: формат выдачи результата запроса при клике по карте ('object' - в виде объекта, 'all' - в виде объекта и в html формате; по умолчанию в html формате);
measure: включает и выключает возможность измерения расстояния на карте с помощью мыши;
message: включает и выключает вывод информационных сообщений на карте;
fullView: кнопка для перехода на полный вид;
tileselect: включает и выключает меню выбора тайловой подложки;
area: выбор области на карте, позволяет выбрать область с помощью мыши на карте;
lang: локализация интерфейса библиотеки ('ru' - русский (по умолчанию), 'en' - английский);
tools: массив кнопок на карте. Доступные варианты: query, queryclick, querybox, measure, measurebox, areabox, areapolygon;
active: массив активных инструментов из одного элемента. Доступные варианты: query, queryclick, querybox, measure, measurebox, areabox, areapolygon.

Инструменты (для массива tools и active):

query, queryclick: запрос по клику на карте;
querybox: запрос по прямоугольной области на карте;
measure: измерение расстояния с помощью линейки;
measurebox: измерение площади;
areabox: выбор прямоугольной области;
areapolygon: выбор произвольной области.


Загрузка настроек ресурса

Формат ресурса геопортала на странице задается в виде объекта: 

var mapConfig = {
    id: <id>,
    sid: <sid>,
    key: <key>
};
map = new kuboMap.Map('map', mapOptions, mapConfig, initView);

Доступны следующие настройки:

id - идентификатор ресурса (string);
sid - идентификатор сессии (string);
key - ключ ресурса (используется вместо sid) (string).

Например: 

<div id="map" style="width: 100%; height: 100%;"></div>

<script type="text/javascript">
    var map = null;
    window.onload = function() {
        map = new kuboMap.Map('map', {}, { id: 'code', sid: 'session' }, {});
    }
</script>

Установка начальной позиции карты

Формат начального масштаба отображения и позиции карты задается в виде объекта: 

var initView = {
    x: <pos X>,
    y: <pos Y>,
    zoom: <zoom>,
    tile: <tile>
};
map = new kuboMap.Map('map', mapOptions, mapConfig, initView);

Доступны следуюшие настройки:

x - позиция по оси X (float);
y - позиция по оси Y (float);
zoom - масштаб (integer);
tile - тайловая подложка (string).

Доступные тайловые подложки:

"" - без подложки (по умолчанию),
base - Карта-схема,
topo - Топооснова,
topo_label - Топооснова (подписи),
label - Подписи,
landsat2012 - Спутник (Landsat2012),
landsat2014 - Спутник (Landsat2014),
landsat2016 - Спутник (Landsat2016),
sentinel2016 - Спутник (Sentinel),
relief_light - Рельеф (светлая),
relief_dark - Рельеф (темная),
bpd_light - БПД (светлая),
bpd_dark - БПД (темная),
osm - OSM Mapnik,
osm_opentopo - OpenTopoMap,
osm_sputnik - Спутник,
yandex_street - Yandex (обычная),
yandex_hybrid - Yandex (гибрид),
yandex_satellite - Yandex (спутник),
google_street - Google (обычная),
google_hybrid - Google (гибрид),
google_satellite - Google (спутник),
google_physics - Google (физическая),
arcgis_worldtopo - ESRI Топографическая,
arcgis_worldstreet - ESRI Улицы,
arcgis_worldterrain - ESRI Ландшафт,
arcgis_worldrelief - ESRI Рельеф,
arcgis_worldimagery - ESRI Изображение.

Подложки yandex_* и google_* работают с ограничениями и использовать не рекомендуется.

Пример: 

var initView = {
    x: 16495486,
    y: 6209437,
    zoom: 10
};
map = new kuboMap.Map('map', mapOptions, mapConfig, initView);

Готовность API карты

Т.к. загрузка настроек карты выполняется после загрузки страницы, необходимо использовать функцию ready для работы с картой и инициализацией новых объектов на карте.
Функция ready исполняет включенный в нее код после того, как будет загружены все настройки заданной карты.
Ниже представлен пример вызова функции ready: 

map = new kuboMap.Map('map', mapOptions, mapConfig, initView);
map.ready( function() {
    alert('Карта загружена!');
});

Элементы управления

Добавление легенды

<legend object> = <map object>.initLegend(<html element>, <parameters>);

<map object> - карта (object);
<html element> - элемент страницы для легенды (HTMLElement Object);
<parameters> - дополнительные параметры (object).

Пример: 

map.initLegend("legend", { top: "4px", left: "4px", groupclass: true });

Добавление объекта поиска по строке

Для поиска по строке адреса или строке координат можно получить объект, инициализировав поиск: 

<search object> = <map object>.initSearch();

<map object> - карта (object);

Объект поиска <search object> имеет метод search(<string>) с параметром в виде строки поиска. Вызов этого метода запускает поиск по строке.

Пример: 

var search = map.initSearch();

Добавление объекта для выбора области начального и полного вида

Для выбора области начального и полного вида можно получить объект: 

<extentbox object> = <map object>.initExtentBox(<html element>, <init array>, <full array>);

<map object> - карта (object);
<html element> - элемент страницы для активного блока (HTMLElement Object);
<init array> - экстенты начального вида (Array<float, float, float, float>);
<full array> - экстенты полного вида (Array<float, float, float, float>).

Объект выбора области <extentbox object> имеет следующие методы:

activate() - активация объекта;
deactivate() - деактивация объекта;
getExtent() - получение экстентов начального и полного вида (Array<Array<float, float, float, float>, Array<float, float, float, float>>);
setExtent(<init array>, <full array>) - установка экстентов начального и полного вида (Array<float, float, float, float>, Array<float, float, float, float>).

Пример: 

var extent = map.initExtentBox(document.getElementById('extent'), [16476795, 6198328, 16507982, 6221749], [16472877, 6192354, 16513594, 6229293]);

Установка настроек объекта для выбора области

Для установки настроек выбора области на карте можно иницилизировать объект: 

<map object>.initArea(<type>, <area array>);

<map object> - карта (object);
<type> - тип выбора области (polygon - полигон, box - прямоугольник) (string);
<area array> - WKT строка с полигоном (<string>) или массив точек полигона ((x0,y0),(x1,y1),...) (Array<point>, где <point> - массив координат [x, y])) (необязательный параметр);

Пример: 

map.initArea('box');

Маркеры на карте

Добавление маркера на карту

<marker object> = <map object>.addMarker(<x>, <y>, <options>);

<marker object> - объект с маркером;
<map object> - карта (object);
<x>, <y> - координаты объекта в проеции карты;
<options> - настройки маркера.

Доступные настройки маркера:

img: url изображения маркера;
anchor: центр изображения маркера, по умолчанию [0.5, 0.5];
offset: сдвиг изображения маркера относительно его центра в пикселях, по умолчанию [0, 0];
attributes: атрибуты объекта.

Пример: 

var marker = map.addMarker(16495486, 6209437, {
    img: 'images/icon.png',
    anchor: [0.5, 1],
    attributes: { 'id': 49 }
});

Удаление маркера с карты

<map object>.removeMarker(<marker object>);

<map object> - карта (object);
<marker object> - объект с маркером.

Пример: 

map.removeMarker(marker);

Удаление всех маркеров с карты

<map object>.clearMarkers();

<map object> - карта (object).

Пример: 

map.clearMarkers();

Добавление обработчика выбора для маркеров

<map object>.setMarkersAction(<function select>);

<map object> - карта (object);
<function select> - обработчик события при клике на маркере (function({position, attr})).

Пример: 

map.setMarkersAction(function(obj) {
    map.addPopup(obj.position[0], obj.position[1], 'ID: ' + obj.attr.id);
});

События

Добавление обработчика событий для клика по карте

<map object>.setQueryAction(<function select>);

<map object> - карта (object);
<function select> - обработчик события при клике на карте (function({html, query, position})).

В качестве параметра для обработчиков событий передается объект со следующими свойствами:

html - результат запроса в html формате (если queryType не задан или установлен в 'all');
query - результат запроса в виде массива формата [attributes (набор полей), data (набор данных)] (если queryType установлен в 'object' или 'all');
position - координаты объекта [x,y].

Пример: 

map.setQueryAction(function(obj) {
    var text = '<b>Информация</b><br>'+obj.query[0].data[0][0];
    map.addPopup(obj.position[0], obj.position[1], text);
});

или 

map.setQueryAction(function(obj) {
    map.addPopup(obj.position[0], obj.position[1], obj.html);
});

Добавление обработчика событий для поиска по строке

<map object>.setSearchAction(<function select>);

<map object> - карта (object);
<function select> - обработчик события при поиске по строке (function({type, result})).

В качестве параметра для обработчиков событий передается объект со следующими свойствами:

type - 1 - поиск по координате, 2 - поиск по строке;
result - результат запроса в виде массива:

для type = 1 массив, преобразованых в проекцию карты координат в формате [x ,y],
для type = 2 массив результатов поиска в формате Array<search result>. Где <search result> объект {text, wkt, description} (text - строка с результатом поиска, description - описание, wkt - массив координат в формате [x, y])

Пример: 

map.setSearchAction(function(obj) {
    if (json.type == 1) map.mapTo(obj.result[0], obj.result[1]);
    if ((json.type == 2) && (json.result.length > 0)) console.log(obj.result[0].wkt[0], obj.result[0].wkt[1]);
});

Добавление обработчика событий для выбора области

<map object>.setAreaAction(<function select>);

<map object> - карта (object);
<function select> - обработчик события при выборе области (function({proj, points})).

В качестве параметра для обработчиков событий передается объект со следующими свойствами:

proj - код проекции;
points - массив координат области в формате [[x0, y0], [x1, y1], [x2, y2], ...].

Пример: 

map.setAreaAction(function(obj) {
    console.log(obj.points);
});

Добавления обработчика событий при обновлении карты после смены подложки

<map object>.setRebuildMapAction(<function select>);

<map object> - карта (object);
<function select> - обработчик события при обновлении карты после смены подложки (function({})).

Пример: 

map.setRebuildMapAction(function(obj) {
    console.log('reload');
});

Получение объекта для выдачи сообщений на карте

<message object> = <map object>.getMessageObject();

<message object> - объект для вывода сообщений (object);
<map object> - карта (object).

Пример: 

var message = map.getMessageObject();

Операции

Переход к точке

<map object>.mapTo(<pos x>, <pos y>, <zoom>);

<map object> - карта (object);
<pos x> - координата X (float);
<pos y> - координата Y (float);
<zoom> - масштабный уровень, необязательный параметр (integer).

Пример: 

map.mapTo(16495486, 6209437, 10);

Переход к области

<map object>.mapToBox(<left>, <bottom>, <right>, <top>);

<map object> - карта (object);
<left> - координата левого края (float);
<bottom> - координата нижнего края (float);
<right> - координата правого края (float);
<top> - координата верхнего края (float).

Пример: 

map.mapToBox(16496255, 6206643, 16500100, 6210008);

Преобразование координат точки из геодезической системы к системе проекта

<coords> = <map object>.getPointFromWGS(<x>, <y>);

<coords> - координаты точки в системе проекта [x, y] (array);
<map object> - карта (object);
<x> - координата X (float);
<y> - координата Y (float).

Пример: 

var xy = map.getPointFromWGS(92, 56);

Версия от 02.03.2021


2008—2021 © ИВМ СО РАН Геопортал ИВМ СО РАН, Красноярск, 2021 Лицензионное Соглашение