Встраивание карт

В этом руководстве рассказывается, как встроить интерактивную карту на веб-страницу.

Создайте URL Maps Embed API

Ниже приведен пример URL, который загружает Maps Embed API:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Заменить:

Добавьте URL в iframe.

Чтобы использовать Maps Embed API на веб-странице, укажите созданный URL в качестве значения атрибута src элемента iframe. Размер карты можно задать с помощью атрибутов height и width тега iframe, например:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

В приведенном выше примере iframe используются дополнительные свойства:

  • Свойство allowfullscreen, позволяющее разворачивать определенные части карты в полноэкранный режим.
  • Свойства frameborder="0" и style="border:0", которые удаляют стандартную рамку iframe вокруг карты.
  • Свойство referrerpolicy="strict-origin-when-cross-origin" гарантирует, что браузер отправит домен вашего сайта в Google в качестве заголовка Referer. Это позволяет ограничениям ключа API проверять запрос, сохраняя конфиденциальность путей к страницам.

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

Информация о реферере и ограничения ключа API

Если на сайте, где размещено объявление, метатег referrer имеет значение no-referrer или same-origin, браузер не будет отправлять заголовок Referer в Google. Из-за этого ограничение ключа API может отклонять запросы. Чтобы ограничение работало правильно, добавьте в iframe свойство referrerpolicy, как в примере выше, чтобы явно разрешить отправку заголовков Referer в Google.

  • strict-origin-when-cross-origin (рекомендуется) – в Google отправляется только ваш основной домен (например, https://example.com/). Это позволит сохранить конфиденциальность путей к страницам, не нарушая работу ограничений ключа API.
  • no-referrer-when-downgrade (устаревший вариант) – отправляется весь URL, включая пути к страницам и параметры запроса (например, https://example.com/contact?user=123).

Подробнее о заголовке Referrer-Policy…

Как выбрать режим карты

В URL запроса можно указать один из следующих режимов карты:

  • place – показывает маркер на карте в определенном месте или по определенному адресу, например у достопримечательности, компании, географического объекта или города.
  • view – возвращает карту без маркеров и маршрутов.
  • directions – показывает путь между двумя или более указанными точками на карте, а также расстояние и время в пути.
  • streetview – интерактивные панорамные изображения, снятые в определенных местах.
  • search – показывает результаты поиска по видимой области карты.

Режим "place"

В следующем URL используется режим карты place, чтобы показать маркер на Эйфелевой башне:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Вы можете использовать следующие параметры:

Параметр Тип Описание Допустимые значения
q Обязательно Определяет местоположение маркера на карте. Название места, адрес, код Plus Code или идентификатор места, экранированные в URL. Maps Embed API поддерживает как +, так и %20 при экранировании пробелов. Например, преобразуйте "City Hall, New York, NY" в City+Hall,New+York,NY или код Plus Code "849VCWC8+R9" в 849VCWC8%2BR9.
center Необязательно Определяет центр карты. Принимает значения широты и долготы, разделенные запятой, например 37.4218,-122.0840.
zoom Необязательно Задает начальный уровень масштабирования карты. Значения варьируются от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.
maptype Необязательно Определяет тип загружаемых фрагментов карты. roadmap (по умолчанию) или satellite
language Необязательно Определяет язык, который будет использоваться для элементов интерфейса и меток на фрагментах карты. По умолчанию посетители видят карту на своем языке. Этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
region Необязательно Определяет, какие границы и названия следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр), который соответствует известным двухсимвольным значениям национального домена верхнего уровня. Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

Режим "view"

В следующем примере используется режим view и необязательный параметр maptype, чтобы показать спутниковую карту:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Вы можете использовать следующие параметры:

Параметр Тип Описание Допустимые значения
center Обязательно Определяет центр карты. Принимает значения широты и долготы, разделенные запятой, например 37.4218,-122.0840.
zoom Необязательно Задает начальный уровень масштабирования карты. Значения варьируются от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.
maptype Необязательно Определяет тип загружаемых фрагментов карты. roadmap (по умолчанию) или satellite
language Необязательно Определяет язык, который будет использоваться для элементов интерфейса и меток на фрагментах карты. По умолчанию посетители видят карту на своем языке. Этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
region Необязательно Определяет, какие границы и названия следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр), который соответствует известным двухсимвольным значениям национального домена верхнего уровня. Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

Режим "directions"

В следующем примере используется режим directions, чтобы показать маршрут между Осло и Телемарком (Норвегия), расстояние и время в пути без платных дорог и автомагистралей.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Вы можете использовать следующие параметры:

Параметр Тип Описание Допустимые значения
origin Обязательно Определяет начальную точку маршрута. Название места, адрес, код Plus Code, координаты широты и долготы или идентификатор места, экранированные в URL. Maps Embed API поддерживает как +, так и %20 при экранировании пробелов. Например, преобразуйте "City Hall, New York, NY" в City+Hall,New+York,NY или код Plus Code "849VCWC8+R9" в 849VCWC8%2BR9.
destination Обязательно Определяет конечную точку маршрута. Название места, адрес, код Plus Code, координаты широты и долготы или идентификатор места, экранированные в URL. Maps Embed API поддерживает как +, так и %20 при экранировании пробелов. Например, преобразуйте "City Hall, New York, NY" в City+Hall,New+York,NY или код Plus Code "849VCWC8+R9" в 849VCWC8%2BR9.
waypoints Необязательно Указывает одно или несколько промежуточных мест для маршрута между пунктом отправления и пунктом назначения. Название, адрес или идентификатор места. Если путевых точек несколько, их нужно разделить вертикальной чертой (|), например Berlin,Germany|Paris,France. Можно указать до 20 путевых точек.
mode Необязательно Определяет способ передвижения. Если режим не указан, Maps Embed API покажет один или несколько наиболее подходящих режимов для указанного маршрута. driving, walking (предпочтительны пешеходные дорожки и тротуары, если они есть), bicycling (предпочтительны велосипедные дорожки и улицы, где удобнее передвигаться на велосипеде, если они есть), transit или flying.
avoid Необязательно Указывает, какие объекты следует избегать при построении маршрута. Обратите внимание, что это не исключает маршруты, включающие указанные объекты, а лишь позволяет выбрать более предпочтительные маршруты. tolls, ferries и/или highways. Если значений несколько, разделите их вертикальной чертой (например, avoid=tolls|highways).
units Необязательно Указывает систему мер (метрическую или английскую), которая будет использоваться для отображения расстояний в результатах. Если параметр units не задан, единицы измерения определяются по стране, из которой поступил запрос origin. metric или imperial
center Необязательно Определяет центр карты. Принимает значения широты и долготы, разделенные запятой, например 37.4218,-122.0840.
zoom Необязательно Задает начальный уровень масштабирования карты. Значения варьируются от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.
maptype Необязательно Определяет тип загружаемых фрагментов карты. roadmap (по умолчанию) или satellite
language Необязательно Определяет язык, который будет использоваться для элементов интерфейса и меток на фрагментах карты. По умолчанию посетители видят карту на своем языке. Этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
region Необязательно Определяет, какие границы и названия следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр), который соответствует известным двухсимвольным значениям национального домена верхнего уровня. Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

Режим "streetview"

Maps Embed API позволяет показывать изображения Просмотра улиц в виде интерактивных панорам для определенных мест в области охвата. Также доступны фотосферы, добавленные пользователями, и специальные коллекции Просмотра улиц.

Каждая панорама в Просмотре улиц обеспечивает полный круговой обзор из одной точки. Изображения обеспечивают обзор в 360° по горизонтали и 180° по вертикали. Режим streetview позволяет просматривать панораму в виде сферы, в центре которой находится камера. Манипулируя камерой, можно управлять ее ориентацией и масштабом.

Посмотрите на панораму в режиме streetview:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

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

  • location принимает значения широты и долготы, разделенные запятыми (46.414382,10.013988). API показывает панораму, снятую ближе всего к этому местоположению. Поскольку изображения Просмотра улиц периодически обновляются, а фотографии каждый раз могут быть сделаны с немного разных позиций, возможно, что при обновлении изображений ваше местоположение может привязаться к другой панораме.

  • pano – идентификатор панорамы. Если вы указываете pano, то можете также указать location. Объект location используется, только если API не может найти идентификатор панорамы.

Следующие параметры URL-адреса являются необязательными.

Параметр Тип Описание Допустимые значения
heading Необязательно Указывает направление камеры по компасу в градусах по часовой стрелке от севера. Значение в градусах от -180° до 360°
pitch Необязательно определяет угол наклона камеры вверх или вниз. Положительные значения наклоняют камеру вверх, а отрицательные – вниз. Значение по умолчанию (0°) устанавливается на основе положения камеры в момент съемки. Поэтому наклон 0° часто, но не всегда, является горизонтальным. Например, при съемке панорамы на холме угол наклона по умолчанию не будет горизонтальным. Значение в градусах от -90° до 90°
fov Необязательно определяет горизонтальную зону обзора изображения. По умолчанию оно равно 90°. При работе с областью просмотра фиксированного размера зона обзора может считаться уровнем масштабирования, причем меньшие значения указывают на более высокий уровень масштабирования. Значение в градусах в диапазоне от 10° до 100°
center Необязательно Определяет центр карты. Принимает значения широты и долготы, разделенные запятой, например 37.4218,-122.0840.
zoom Необязательно Задает начальный уровень масштабирования карты. Значения варьируются от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.
maptype Необязательно Определяет тип загружаемых фрагментов карты. roadmap (по умолчанию) или satellite
language Необязательно Определяет язык, который будет использоваться для элементов интерфейса и меток на фрагментах карты. По умолчанию посетители видят карту на своем языке. Этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
region Необязательно Определяет, какие границы и названия следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр), который соответствует известным двухсимвольным значениям национального домена верхнего уровня. Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

Режим "search"

В режиме Search показываются результаты поиска в видимой области карты. Рекомендуется определить местоположение для поиска, включив его в поисковый запрос (record+stores+in+Seattle) или добавив параметры center и zoom, чтобы ограничить поиск.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Вы можете использовать следующие параметры:

Параметр Тип Описание Допустимые значения
q Обязательно Определяет поисковый запрос. Можно указать географическое ограничение, например in+Seattle или near+98033.
center Необязательно Определяет центр карты. Принимает значения широты и долготы, разделенные запятой, например 37.4218,-122.0840.
zoom Необязательно Задает начальный уровень масштабирования карты. Значения варьируются от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения.
maptype Необязательно Определяет тип загружаемых фрагментов карты. roadmap (по умолчанию) или satellite
language Необязательно Определяет язык, который будет использоваться для элементов интерфейса и меток на фрагментах карты. По умолчанию посетители видят карту на своем языке. Этот параметр поддерживается только для фрагментов некоторых стран. Если запрошенный язык не поддерживается для набора фрагментов, будет использоваться язык по умолчанию.
region Необязательно Определяет, какие границы и названия следует показывать, с учетом геополитических особенностей. Принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр), который соответствует известным двухсимвольным значениям национального домена верхнего уровня. Список поддерживаемых регионов приведен в статье Доступность сервисов платформы Google Карт.

Параметры идентификатора места

Maps Embed API позволяет использовать идентификаторы мест вместо их названий или адресов. Идентификаторы мест – это надежный способ уникальной идентификации места. Дополнительную информацию можно найти в документации по Places API (New).

Maps Embed API принимает идентификаторы мест для следующих параметров URL:

  • q
  • origin
  • destination
  • waypoints

Чтобы использовать идентификатор места, сначала добавьте префикс place_id:. В следующем коде в качестве начальной точки маршрута указана мэрия Нью-Йорка: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius задает радиус в метрах, в пределах которого выполняется поиск панорамы с центром в указанных широте и долготе. Допустимые значения – неотрицательные целые числа. Значение по умолчанию – 50.

  • source – поиск в Просмотре улиц ограничен заданными источниками. Допустимые значения:

    • default – источники Просмотра улиц по умолчанию (поиск не ограничен заданными источниками);
    • outdoor – только уличные фотографии Коллекции, снятые в помещениях, не включаются в результаты поиска. Обратите внимание, что для указанного местоположения может не найтись панорамы, снятой вне помещений. Обратите внимание, что в результатах поиска будут только панорамы, для которых можно определить, где они были сняты – в помещении или вне его. Например, фотосферы не возвращаются, поскольку неизвестно, где они были сделаны – в помещении или на улице.