API статических изображений

API статических изображений (Static Image API) в экосистеме HERE Maps предназначен для генерации готовых изображений карт без необходимости загружать интерактивный картографический интерфейс в браузер. В ответ на HTTP-запрос сервис возвращает изображение в формате PNG или JPEG, содержащее указанный участок карты с заданными параметрами отображения.

Подобный подход особенно востребован в следующих сценариях:

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

В отличие от интерактивного JavaScript API, Static Image API не требует инициализации карты, загрузки тайлов и выполнения клиентского кода визуализации.

Принцип работы

Работа сервиса основана на формировании URL-запроса с набором параметров.

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

https://image.maps.ls.hereapi.com/mia/1.6/mapview
    ?apiKey=YOUR_API_KEY
    &c=52.53086,13.38469
    &z=14
    &w=800
    &h=600

После обработки запроса сервер HERE генерирует готовое изображение карты.

В JavaScript обычно создается URL, который затем используется:

  • как источник изображения (img);
  • для скачивания файла;
  • для передачи в сторонние сервисы;
  • для сохранения в базе данных.

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

Для работы требуется ключ доступа платформы HERE.

Пример параметра авторизации:

const apiKey = 'YOUR_API_KEY';

Затем ключ добавляется в URL:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview?apiKey=${apiKey}`;

Все запросы к сервису должны содержать действительный API Key.

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

Минимальный запрос обычно включает:

  • координаты центра;
  • масштаб;
  • ширину изображения;
  • высоту изображения.

Пример:

const apiKey = 'YOUR_API_KEY';

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

document.querySelector('#map').src = url;

HTML:

<img id="map" alt="Static Map">

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

Центрирование карты

Параметр c определяет центр изображения.

Формат:

latitude,longitude

Пример:

const center = '40.7128,-74.0060';

Для отображения Нью-Йорка:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=${center}` +
  `&z=12` +
  `&w=1000` +
  `&h=600`;

Масштаб карты

Параметр z отвечает за уровень приближения.

Пример:

z=3

Отображение целой страны.

z=8

Отображение региона.

z=15

Отображение кварталов.

z=18

Высокая детализация улиц и зданий.

Пример:

const zoom = 16;

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

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=48.8584,2.2945` +
  `&z=${zoom}` +
  `&w=900` +
  `&h=700`;

Размер изображения

Размеры определяются параметрами:

  • w — ширина;
  • h — высота.

Пример:

const width = 1200;
const height = 800;

URL:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=51.5074,-0.1278` +
  `&z=12` +
  `&w=${width}` +
  `&h=${height}`;

Большие изображения полезны при печати и генерации отчетов.

Изменение типа карты

Static Image API позволяет использовать различные стили отображения.

Параметр:

t

Пример:

&t=0

Стандартная дорожная карта.

&t=1

Спутниковое изображение.

&t=2

Рельефная карта.

Пример:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=35.6762,139.6503` +
  `&z=13` +
  `&w=1000` +
  `&h=600` +
  `&t=1`;

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

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

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

Параметр:

poix

Пример:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=52.53086,13.38469` +
  `&z=14` +
  `&w=800` +
  `&h=600` +
  `&poix=52.53086,13.38469;red;A`;

Здесь:

  • координаты маркера;
  • цвет;
  • текстовая метка.

Результат — карта с красным маркером и подписью.

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

Допускается добавление нескольких объектов.

Пример:

const markers = [
  '52.53086,13.38469;red;A',
  '52.52000,13.41000;blue;B',
  '52.51000,13.43000;green;C'
];

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&c=52.53086,13.38469` +
  `&z=12` +
  `&w=900` +
  `&h=700` +
  markers.map(m => `&poix=${encodeURIComponent(m)}`).join('');

На карте появятся три независимых маркера.

Пользовательские подписи

Маркеры могут содержать произвольный текст.

Пример:

const location =
  '48.8566,2.3522;red;Office';

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

&poix=48.8566,2.3522;red;Office

Результатом станет маркер с надписью:

Office

Изменение цвета маркеров

Поддерживаются различные цвета.

Пример:

const redMarker =
  '55.7558,37.6176;red;M';
const blueMarker =
  '55.7600,37.6300;blue;B';
const greenMarker =
  '55.7700,37.6100;green;G';

Это позволяет визуально разделять объекты по категориям.

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

Статическое изображение может содержать маршрут, рассчитанный заранее.

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

Пример:

const route =
  '52.5,13.3,52.51,13.35,52.52,13.4';

URL:

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

В ответ будет сформировано изображение маршрута.

Отрисовка полилиний

Полилинии используются для отображения:

  • маршрутов;
  • треков GPS;
  • границ территорий;
  • произвольных геометрий.

Пример:

const polyline =
  '52.50,13.30,52.51,13.35,52.52,13.40';

Формирование запроса:

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview` +
  `?apiKey=${apiKey}` +
  `&w=1000` +
  `&h=700` +
  `&z=13` +
  `&c=52.51,13.35` +
  `&r=${polyline}`;

Генерация изображений на сервере Node.js

Static Image API часто используется в серверных приложениях.

Создание URL:

function buildMapUrl(lat, lng) {
  const apiKey = process.env.HERE_API_KEY;

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

Получение ссылки:

const imageUrl =
  buildMapUrl(52.53086, 13.38469);

Скачивание изображения

Полученный URL можно использовать для загрузки файла.

Пример в браузере:

async function downloadMap(url) {
  const response = await fetch(url);

  const blob = await response.blob();

  const objectUrl =
    URL.createObjectURL(blob);

  const link =
    document.createElement('a');

  link.href = objectUrl;
  link.download = 'map.png';

  link.click();
}

Вызов:

downloadMap(url);

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

Статическая карта может быть встроена в Canvas.

Пример:

const img = new Image();

img.onl oad = () => {
  const canvas =
    document.querySelector('canvas');

  const ctx =
    canvas.getContext('2d');

  ctx.drawImage(img, 0, 0);
};

img.src = url;

Такой подход позволяет дополнительно рисовать поверх карты собственные объекты.

Формирование URL через URLSearchParams

Для безопасного создания запросов удобно использовать объект URLSearchParams.

Пример:

const params =
  new URLSearchParams({
    apiKey,
    c: '52.53086,13.38469',
    z: '14',
    w: '800',
    h: '600'
  });

const url =
  `https://image.maps.ls.hereapi.com/mia/1.6/mapview?${params}`;

Преимущества:

  • автоматическое кодирование параметров;
  • более читаемый код;
  • удобное добавление новых настроек.

Кэширование изображений

Поскольку результатом является обычное изображение, браузеры эффективно используют HTTP-кэш.

Практические преимущества:

  • снижение количества запросов;
  • уменьшение сетевой нагрузки;
  • ускорение повторной загрузки страниц;
  • снижение расходов на использование API.

Типичный подход:

const cache = new Map();

Проверка существования URL:

if (!cache.has(url)) {
  cache.set(url, url);
}

Оптимизация производительности

При работе со статическими картами рекомендуется:

  1. Использовать минимально необходимый размер изображения.
  2. Не запрашивать высокий уровень масштабирования без необходимости.
  3. Использовать кэширование результатов.
  4. Повторно использовать ранее сформированные URL.
  5. Генерировать карты на сервере для массовых операций.
  6. Использовать статические изображения вместо интерактивных карт там, где взаимодействие пользователя не требуется.

Сравнение Static Image API и JavaScript Maps API

Возможность Static Image API JavaScript Maps API
Интерактивность Нет Да
Панорамирование Нет Да
Масштабирование пользователем Нет Да
Маркеры Да Да
Маршруты Да Да
Нагрузка на браузер Низкая Средняя
Подходит для отчетов Да Нет
Подходит для email Да Нет
Подходит для печати Да Ограниченно

Static Image API ориентирован на получение готовых изображений, тогда как JavaScript Maps API предназначен для создания полноценных интерактивных картографических приложений.

Оглавление