Как использовать токены сеанса с Map Tiles API

Разработчики из Европейской экономической зоны (ЕЭЗ)

Токен сеанса – это фрагмент данных (UUID), который используется в вызовах REST для идентификации сеанса – серии связанных обменов сообщениями. Токен сеанса необходимо включать во все запросы двухмерных тайлов и изображений Просмотра улиц. Его нужно добавить в качестве значения параметра session ко всем URL запросов.

В Map Tiles API токен сеанса представляет собой определенный набор параметров отображения. Это означает, что вам не нужно передавать набор параметров показа с каждым запросом тайла. Один и тот же токен сеанса можно использовать для нескольких клиентов. В настоящее время токен сеанса действителен в течение двух недель с момента его выпуска, но это может измениться. Срок действия токена сеанса можно проверить, посмотрев значение поля expiry в сообщении с ответом.

Запрос токена сеанса

Чтобы запросить токен сеанса, отправьте HTTPS-запрос POST в конечную точку createSession, как показано в следующем примере. Запрос должен содержать заголовок Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Обязательные поля

mapType

тип базовой карты. Возможные значения:

roadmap
Стандартные фрагменты Google Карт.
satellite
Спутниковые снимки.
terrain
Изображения рельефа. Если вы выбрали тип карты terrain, необходимо также указать тип слоя layerRoadmap (описан в разделе Необязательные поля).
streetview
Панорамы в Просмотре улиц. Подробнее о плитках Просмотра улиц…
language

Языковой тег IETF, который указывает язык, используемый для отображения информации на элементах. Например, en-US – это английский язык, на котором говорят в США.

region

Идентификатор региона Common Locale Data Repository (две заглавные буквы), который представляет физическое местоположение пользователя. Пример: US.

Необязательные поля

imageFormat
Указывает формат файла, который нужно вернуть. Допустимые значения: jpeg и png. Файлы JPEG не поддерживают прозрачность, поэтому их не рекомендуется использовать для фрагментов наложения. Если вы не укажете imageFormat, то лучший формат для фрагмента будет выбран автоматически.
scale

Увеличивает размер элементов карты (например, названий дорог), сохраняя размер фрагмента и область охвата фрагмента по умолчанию. При увеличении масштаба также уменьшается количество меток на карте, что снижает загроможденность. Допустимые значения scale:

  • scaleFactor1x – значение по умолчанию.
  • scaleFactor2x – увеличивает размер ярлыков в два раза и удаляет ярлыки незначительных объектов.
  • scaleFactor4x – увеличивает размер ярлыков в четыре раза и удаляет ярлыки второстепенных объектов.

В примерах ниже показано, как работает масштабирование элементов карты.

Коэффициент масштабирования 1x Коэффициент масштабирования 2x
Карта с коэффициентом масштабирования 1x Карта с коэффициентом масштабирования 2x
highDpi
Указывает, нужно ли возвращать фрагменты с высоким разрешением. Если коэффициент масштабирования увеличивается, highDpi используется для увеличения размера фрагмента. Обычно увеличение коэффициента масштабирования приводит к увеличению фрагмента до изображения того же размера, что снижает качество. При использовании highDpi размер файла увеличивается, а качество сохраняется. DPI – это количество точек на дюйм. Высокое значение DPI означает, что при отрисовке фрагмента используется больше точек на дюйм, чем обычно. Если задано значение true, то количество пикселей по осям X и Y умножается на коэффициент масштабирования (то есть на 2 или 4). Зона покрытия плитки не изменится. Этот параметр работает только со значениями scale, равными 2x или 4x. Она не влияет на плитки масштаба 1x.
Коэффициент масштабирования 1x Коэффициент масштабирования 2x (высокая плотность точек)
Карта с обычным разрешением Карта, отображаемая с разрешением 2x High DPI
layerTypes

Массив значений, указывающий типы слоев, добавленных на карту. Допустимые значения:

layerRoadmap
Обязательный атрибут, если в качестве типа карты указан атрибут terrain. Также может накладываться на тип карты satellite. Не влияет на фрагменты дорожной карты.
layerStreetview
Улицы и места, для которых доступен Просмотр улиц, выделены на карте синим цветом.
layerTraffic
 – показывает текущую загруженность дорог.
styles

Массив объектов стиля JSON, которые определяют внешний вид и уровень детализации объектов карты, таких как дороги, парки и застроенные территории. Стили используются для настройки стандартной базовой карты Google. Параметр styles действителен, только если тип карты – roadmap. Полный синтаксис стилей приведен в справочной документации по стилям.

overlay

Логическое значение, которое указывает, должен ли слой layerTypes отображаться как отдельный оверлей или в сочетании с базовыми изображениями. Если true, базовая карта не показывается. Если вы не определили layerTypes, это значение игнорируется.

Например, если запросить тип карты satellite со слоем layerRoadmap и задать для параметра overlay значение false, то будут получены фрагменты, эквивалентные типу карты hybrid, используемому в Maps JavaScript API (изображение слева). Если для тех же типов карт и слоев задать для overlay значение true, получится прозрачный фрагмент с наложением данных на карту, стилизованный для наложения на спутниковые снимки (изображение справа).

overlay: false overlay: true
Для оверлея задано значение false Оверлей включен

Ниже приведен пример типичного тела запроса в формате JSON, содержащего как обязательные, так и необязательные поля.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

В этом примере показан оверлей, который можно комбинировать со спутниковыми снимками. В примере показаны как схема проезда, так и наложение Просмотра улиц. В результате на карте будут отображаться названия и данные на английском языке, как в США.

Ответ токена сеанса

Ниже приведен пример текста ответа в формате JSON.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Ниже приведены определения полей в теле ответа.

session
Значение токена сеанса, которое необходимо включать во все запросы к Map Tiles API.
expiry
Строка, содержащая время (в секундах с начала эпохи), когда истекает срок действия токена. Токен сеанса действителен в течение двух недель с момента создания, но это правило может измениться без уведомления.
tileWidth
Ширина фрагментов в пикселях.
tileHeight
Высота фрагментов в пикселях.
imageFormat
Графический формат: png или jpeg.