Сценарии использования | 2GIS Documentation
MapGL JS API
Личный кабинет

Сценарии использования

Если вы только начинаете работу с картой, узнайте об основах её работы и сценариях использования.

Верхнеуровнево карта на MapGL JS API выполняет только одну задачу: отрисовывает данные при помощи стилей.

Данные — информация, которая может быть отображена на карте: здания, дороги, водные объекты, границы областей и многое другое. Это всё, что отвечает на вопрос «Что рисовать?». В большинстве случаев эта информация содержит привязку к какой-либо географической области. Другими словами, это геоданные.

Стили — правила, которые определяют в каком порядке и в каком виде отображать данные карты. Это всё, что отвечает на вопрос «Как рисовать?». Без определения стиля данные не появятся на карте.

Данные и стили могут работать в двух вариантах:


Вы можете как работать с готовыми данными 2ГИС, так и загрузить собственные данные для дополнения информации на карте. Пользовательские данные можно загрузить через динамические объекты или источники данных.

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

Ниже представлены типовые сценарии работы с MapGL JS API, которые помогут вам определить первые шаги для решения вашей задачи.

Используйте этот сценарий, если вам необходимо добавить на карту 2ГИС небольшое количество собственных объектов. Пример: показать на карте места, где в будущем будут открыты новые заведения, и для каждого из них задать уникальный вид иконки.

Шаги:

  1. Инициализируйте карту.
  2. Добавьте динамические объекты и настройте вид каждого из них.
  3. Если необходимо, дополнительно настройте вид карты-подложки в Редакторе стилей.

Пример карты с маркерами, добавленными поштучно:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Several markers example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });
            const coords = [
                [55.27414804174869, 25.257576991034284],
                [55.289254243403306, 25.211614202468652],
                [55.34418588368302, 25.215341562259866],
                [55.35036569359612, 25.26068195798851],
                [55.32976632814914, 25.238324424362062],
            ];
            coords.forEach((coord) => {
                const marker = new mapgl.Marker(map, {
                    coordinates: coord,
                });
            });
        </script>
    </body>
</html>

Если вам не подходят стандартные стили из Редактора, вы можете создать свой стиль на их основе и использовать его в карте. Пример: показать на карте только федеральные трассы и выделить их определённым цветом или настроить светлую и тёмную тему для карты.

Шаги:

  1. Инициализируйте карту.
  2. Настройте отображение нужных слоёв в Редакторе стилей.

Пример карты с подключенными стилями для светлой и темной темы:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Style apply in runtime example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
                font-family: Helvetica, Arial, sans-serif;
            }

            #dark_theme, #light_theme {
                margin: 0 10px 10px;
                padding: 3px 12px;
                background: #3b3b3b;
                color: #fff;
                border: none;
            }
        </style>
    </head>
    <body>
        <div>
            Click to switch theme:
            <button id="dark_theme">Switch to dark theme 🌙</button>
            <button id="light_theme">Switch to light theme 🌞</button>
        </div>

        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.187609, 25.141736],
                styleZoom: 16,
                pitch: 40,
                rotation: -45,
                key: 'Your API access key',
            });

            document.getElementById('dark_theme').addEventListener('click', function() {
                map.setStyleById('e05ac437-fcc2-4845-ad74-b1de9ce07555');
            });
            document.getElementById('light_theme').addEventListener('click', function() {
                map.setStyleById('c080bb6a-8134-4993-93a1-5b4d8c36a59b');
            });
        </script>
    </body>
</html>

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

Шаги:

  1. Инициализируйте карту.
  2. Добавьте источник данных.
  3. Настройте стилевой слой при помощи метода map.addLayer() и спецификации стилей или создайте его в Редакторе стилей.

Пример карты с подключенным источником GeoJSON и настроенной стилизацией в виде тепловой карты:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Heatmap layer example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.26020, 25.17429],
                zoom: 11,
                key: 'Your API access key',
            });

            fetch('/samples/traffic_accidents.csv')
                .then(r => r.text())
                .then(text => {
                    const csv = text.split('\n').map(s => s.split(','));

                    const geojson = {
                        type: 'FeatureCollection',
                        features: []
                    };

                    const count = csv.length - 1;
                    console.log(count);

                    csv
                        .slice(1) // removes the header row
                        .forEach((row) => {
                            if (row.length < 5) {
                                return;
                            }
                            geojson.features.push({
                                type: 'Feature',
                                properties: { customProperty: 900 / count },
                                geometry: {
                                    type: 'Point',
                                    coordinates: [
                                        // Parse coordinates from CSV encoding to number
                                        +JSON.parse(row[4]),
                                        +JSON.parse(row[3])
                                    ],
                                },
                            });
                        });

                    const source = new mapgl.GeoJsonSource(map, {
                        data: geojson,
                        attributes: {
                            purpose: 'heatmap',
                        },
                    });
                });

            
            const layer = {
                id: 'my-heatmap-layer', // Each layer ID must be unique

                // Data filtering logic
                filter: [
                    'match',
                    ['sourceAttr', 'purpose'],
                    ['heatmap'],
                    true, // Result if value of purpose source attribute equals "heatmap"
                    false, // Result if not
                ],

                // Drawing object type
                type: 'heatmap',

                // Style of drawing object
                style: {
                    color: [
                        'interpolate',
                        ['linear'],
                        ['heatmap-density'],
                        0,
                        'rgba(0, 0, 0, 0)',
                        0.2,
                        'rgba(172, 32, 135, 1)',
                        0.4,
                        'rgba(255, 154, 0, 1)',
                        0.6,
                        'rgba(255, 252, 0, 1)',
                        0.8,
                        'rgba(255, 255, 63, 1)',
                        1,
                        'rgba(255, 255, 255, 1)',
                    ],
                    radius: 30,
                    weight: ["get", "customProperty"],
                    intensity: 0.4,
                    opacity: 0.8,
                    downscale: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer, '70184');
            });
        </script>
    </body>
</html>