Генерация статических карт

Статические карты (Static Maps) представляют собой изображения картографических данных, формируемые сервером и возвращаемые в виде готового графического файла. В отличие от интерактивных карт, основанных на объекте H.Map, статическая карта не содержит элементов управления, не поддерживает масштабирование пользователем и не требует выполнения сложной клиентской логики.

В экосистеме HERE Maps статические карты применяются для решения широкого спектра задач:

отображение карт в электронных письмах;
генерация миниатюр маршрутов;
создание изображений для отчетов;
интеграция карт в PDF-документы;
отображение местоположений в карточках объектов;
использование в системах уведомлений;
генерация превью маршрутов и географических объектов.

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

Архитектура Static Maps API

Генерация статической карты выполняется через HTTP-запрос к серверу HERE.

Общая схема выглядит следующим образом:

Клиент формирует URL с параметрами.
Запрос отправляется на сервер HERE.
Сервер генерирует изображение.
Готовая карта возвращается в формате PNG или JPEG.
Изображение отображается в браузере через тег <img>.

С точки зрения JavaScript статическая карта является обычным изображением, URL которого содержит набор параметров для настройки внешнего вида.

Подключение API-ключа

Для работы необходимо получить API Key в консоли разработчика HERE.

После создания проекта формируется ключ:

const apiKey = 'YOUR_API_KEY';

Далее он передается в параметры URL.

Базовый запрос статической карты

Простейший пример отображения карты города:

<img
  src="https://image.maps.ls.hereapi.com/mia/1.6/mapview
       ?apiKey=YOUR_API_KEY
       &c=55.7512442,37.618423
       &z=12
       &w=800
       &h=500"
>

Здесь используются следующие параметры:

Параметр	Описание
c	Координаты центра
z	Масштаб
w	Ширина изображения
h	Высота изображения
apiKey	Ключ доступа

Результатом станет изображение карты Москвы с указанным масштабом.

Формирование URL в JavaScript

Чаще всего адрес создается программно.

function createStaticMapUrl(lat, lng) {
    const apiKey = 'YOUR_API_KEY';

    return `https://image.maps.ls.hereapi.com/mia/1.6/mapview
        ?apiKey=${apiKey}
        &c=${lat},${lng}
        &z=14
        &w=800
        &h=600`;
}

Использование:

const image = document.createElement('img');

image.src = createStaticMapUrl(
    55.751244,
    37.618423
);

document.body.appendChild(image);

Настройка размеров изображения

Размер карты задается параметрами:

w
h

Пример:

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.751244,37.618423
&z=13
&w=1200
&h=800`;

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

Управление масштабом

Масштаб карты задается параметром:

Типичные значения:

Масштаб	Назначение
3	Континент
5	Страна
8	Регион
12	Город
15	Район
18	Улица
20	Здание

Пример:

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.751244,37.618423
&z=18
&w=800
&h=600`;

Карта будет сфокусирована на небольшом городском участке.

Выбор типа карты

HERE предоставляет несколько вариантов отображения.

Параметр:

Основные значения:

Значение	Тип
0	Нормальная карта
1	Спутниковая
2	Гибрид
3	Рельеф

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

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.751244,37.618423
&z=14
&t=1
&w=800
&h=600`;

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

Одной из наиболее востребованных возможностей является отображение точек интереса.

Пример:

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.751244,37.618423
&z=13
&w=800
&h=600
&poix0=55.751244,37.618423;ff0000;ffffff;15;A`;

Параметр poix0 описывает маркер.

Структура:

latitude,longitude;
markerColor;
textColor;
size;
label

Результат:

красный маркер;
белая подпись;
размер 15;
буква A внутри значка.

Несколько маркеров

Количество маркеров не ограничивается одной точкой.

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.751244,37.618423
&z=11
&w=1000
&h=700
&poix0=55.751244,37.618423;ff0000;ffffff;15;A
&poix1=55.761244,37.648423;0000ff;ffffff;15;B
&poix2=55.731244,37.598423;00aa00;ffffff;15;C`;

На карте будут одновременно отображены три точки.

Создание массива маркеров

При динамической генерации удобнее использовать массив данных.

const markers = [
    {
        lat: 55.75,
        lng: 37.61,
        label: 'A'
    },
    {
        lat: 55.76,
        lng: 37.65,
        label: 'B'
    },
    {
        lat: 55.73,
        lng: 37.59,
        label: 'C'
    }
];

Формирование URL:

const params = markers
    .map((marker, index) => {
        return `poix${index}=${marker.lat},
                ${marker.lng};
                ff0000;
                ffffff;
                15;
                ${marker.label}`;
    })
    .join('&');

Создание итогового адреса:

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${apiKey}
&c=55.75,37.61
&z=12
&w=1000
&h=700
&${params}`;

Отображение маршрутов

Статические карты позволяют визуализировать маршрут между точками.

Маршрут обычно строится через Routing API, после чего полученная геометрия передается в Static Maps API.

Схема работы:

Routing API
      ↓
Получение polyline
      ↓
Static Map API
      ↓
Готовое изображение маршрута

Подход активно используется в:

транспортных системах;
логистике;
сервисах доставки;
системах мониторинга транспорта.

Использование полилиний

После получения геометрии маршрута формируется параметр линии.

Пример структуры:

const polyline =
'55.75,37.61,55.76,37.63,55.77,37.65';

URL:

const url =
`https://image.maps.ls.hereapi.com/mia/1.6/route
?apiKey=${apiKey}
&r=${polyline}
&w=1000
&h=700`;

В результате создается изображение маршрута между указанными точками.

Генерация карты по маршруту доставки

Допустим имеется список координат курьера.

const points = [
    [55.75, 37.61],
    [55.76, 37.63],
    [55.77, 37.65],
    [55.78, 37.67]
];

Подготовка строки маршрута:

const route = points
    .map(point => point.join(','))
    .join(',');

Создание изображения:

const imageUrl =
`https://image.maps.ls.hereapi.com/mia/1.6/route
?apiKey=${apiKey}
&r=${route}
&w=1200
&h=800`;

Такой подход позволяет генерировать маршрутные карты без подключения полноценного интерактивного интерфейса.

Использование Retina-изображений

Для экранов высокой плотности пикселей необходимо создавать карты большего разрешения.

Пример:

const width = 1600;
const height = 1200;

Отображение:

<img
    width="800"
    height="600"
    src="...">

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

Асинхронная генерация изображений

Часто URL создается после получения данных с сервера.

async function loadMap() {

    const response =
        await fetch('/api/location');

    const location =
        await response.json();

    const image =
        document.querySelector('#map');

    image.src =
        createStaticMapUrl(
            location.lat,
            location.lng
        );
}

Подход удобен при отображении объектов из базы данных.

Интеграция с карточками объектов

Распространенный сценарий — вывод мини-карты рядом с описанием объекта.

<div class="office-card">

    <h3>Главный офис</h3>

    <img id="officeMap">

</div>

Jav * aScript:

document
    .getElementById('officeMap')
    .src =
    createStaticMapUrl(
        55.751244,
        37.618423
    );

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

Кэширование статических карт

Статические изображения хорошо подходят для кэширования.

Возможные варианты:

CDN;
Service Worker;
серверный кэш;
локальное хранилище браузера.

Пример сохранения URL:

localStorage.setItem(
    'officeMap',
    imageUrl
);

Повторная генерация становится ненужной до изменения параметров карты.

Серверная генерация карт

Часто URL формируется на стороне Node.js.

function buildMapUrl(lat, lng) {

    return `
https://image.maps.ls.hereapi.com/mia/1.6/mapview
?apiKey=${process.env.HERE_API_KEY}
&c=${lat},${lng}
&z=14
&w=800
&h=600`;

}

Далее адрес передается в шаблонизатор:

res.render('office', {
    mapUrl: buildMapUrl(
        office.lat,
        office.lng
    )
});

Шаблон:

<img src="<%= mapUrl %>">

Использование статических карт в PDF

Одной из наиболее сильных сторон Static Maps API является возможность вставки изображений в документы.

Последовательность работы:

Получение URL карты
      ↓
Загрузка изображения
      ↓
Вставка в PDF
      ↓
Генерация отчета

Такой подход широко применяется в:

логистических отчетах;
транспортных ведомостях;
геоинформационных системах;
CRM-системах;
системах контроля выездных сотрудников.

Ограничения статических карт

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

отсутствие масштабирования пользователем;
невозможность перетаскивания карты;
отсутствие всплывающих окон;
отсутствие событий клика;
необходимость повторной генерации изображения при изменении параметров;
ограничения по длине URL при большом количестве объектов.

Несмотря на это, статические карты остаются эффективным инструментом для отображения географической информации в ситуациях, где интерактивность не требуется.

Генерация статических карт

Архитектура Static Maps API

Подключение API-ключа

Базовый запрос статической карты

Формирование URL в JavaScript

Настройка размеров изображения

Управление масштабом

Выбор типа карты

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

Несколько маркеров

Создание массива маркеров

Отображение маршрутов

Использование полилиний

Генерация карты по маршруту доставки

Использование Retina-изображений

Асинхронная генерация изображений

Интеграция с карточками объектов

Кэширование статических карт

Серверная генерация карт

Использование статических карт в PDF

Ограничения статических карт

Рекомендации по использованию