Начало работы

Введение

С помощью URL Карт вы можете создать универсальные межплатформенные ссылки для запуска Google Карт. Они поддерживают поиск, просмотр маршрутов, навигацию, а также разные представления карт и панорамные изображения. Синтаксис URL одинаков для всех платформ.

Для использования URL Карт ключ API Google не требуется.

Универсальный кросс-платформенный синтаксис

Разработчики приложений для Android и iOS, а также сайтов могут создавать универсальные URL, которые открывают Google Карты и выполняют запрошенное действие независимо от платформы, на которой открывается карта.

• На устройстве Android:
  • Если на устройстве установлено и активно приложение "Google Карты" для Android, URL запускает его и выполняет запрошенное действие.
  • Если приложение "Google Карты" не установлено или отключено, URL запускает Google Карты в браузере и выполняет запрошенное действие.
• На iOS-устройстве:
  • Если на устройстве установлено приложение "Google Карты" для iOS, URL запустит его и выполнит запрошенное действие.
  • Если приложение "Google Карты" не установлено, URL откроет Google Карты в браузере и выполнит запрошенное действие.
• На любом другом устройстве URL откроет Google Карты в браузере и выполнит запрошенное действие.

Рекомендуем использовать межплатформенные URL для запуска Google Карт из приложения или сайта, поскольку эти универсальные URL позволяют обрабатывать запросы для карт независимо от платформы пользователя. Если вам нужны функции, которые работают только на мобильных платформах (например, пошаговая навигация), выберите вариант для Android или iOS. Ознакомьтесь со следующей документацией:

• Объекты Intent для Google Карт на платформе Android – в частности, для запуска приложения "Google Карты" для Android.
• Схема URL Google Карт для iOS – в частности, для запуска приложения "Google Карты" для iOS.

запуск Google Карт и выполнение определенного действия;

Чтобы запустить Google Карты и выполнить одну из поддерживаемых функций, используйте схему URL одного из следующих форматов в зависимости от запрошенного действия:

• Поиск – запуск Google Карт с маркером определенного места или выполнение общего поискового запроса и запуск карт для показа результатов:
  https://www.google.com/maps/search/?api=1&parameters
• Маршруты. Запросите маршрут и запустите Google Карты с результатами:
  https://www.google.com/maps/dir/?api=1&parameters
• Показать карту – запустить Google Карты без маркеров и маршрутов:
  https://www.google.com/maps/@?api=1&map_action=map&parameters
• Показать панораму в Просмотре улиц – запустить интерактивное панорамное изображение:
  https://www.google.com/maps/@?api=1&map_action=pano&parameters

Важно! Параметр api=1 определяет версию URL Карт, для которой предназначен этот URL. Этот параметр обязателен для каждого запроса. Единственное допустимое значение – 1. Если в URL api=1 отсутствует, все параметры игнорируются и запускается приложение "Google Карты" по умолчанию – в браузере или мобильном приложении "Google Карты", в зависимости от используемой платформы (например, https://www.google.com/maps).

Как создавать действительные URL

URL должны быть правильно закодированы.

Например, в некоторых параметрах в качестве разделителя используется вертикальная черта (|), которую в конечном URL нужно кодировать как %7C. Другие параметры используют значения, разделенные запятыми, например координаты широты и долготы или название города и штата. Запятую нужно закодировать как %2C. Пробелы нужно кодировать символами %20 или заменять знаком плюса (+).

Кроме того, URL для каждого запроса могут содержать не более 2048 символов. Учитывайте это ограничение при создании URL.

Действия на карте

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

Поиск

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

Как создать URL поиска

https://www.google.com/maps/search/?api=1&parameters

Параметры

• query (обязательный параметр) – определяет места, которые нужно выделить на карте. Параметр запроса обязателен для всех поисковых запросов.
  • Укажите местоположения в виде названия места, адреса или координат широты и долготы, разделенных запятой. Строки должны быть закодированы в формате URL, поэтому адрес "City Hall, New York, NY" должен быть преобразован в City+Hall%2C+New+York%2C+NY.
  • Укажите общие поисковые запросы в виде закодированной для URL строки, например grocery+stores или restaurants+in+seattle+wa.
• query_place_id (необязательно). Идентификатор места – это уникальный текстовый идентификатор места. Для действия search необходимо указать query, но вы также можете указать query_place_id. Если вы укажете оба параметра, query будет использоваться только в том случае, если Google Картам не удастся найти идентификатор места. Если вы хотите сослаться на определенное заведение, идентификатор места – лучший способ гарантировать, что вы сошлетесь на правильное место. Также рекомендуется отправлять объект query_place_id при запросе определенного местоположения с помощью координат широты и долготы.

Примеры поисковых запросов

Поиск местоположения

При поиске местоположения вы ищете определенное место, используя название, адрес или координаты широты и долготы, разделенные запятыми. На карте появляется маркер в этом месте. В этих трех примерах показан поиск одного и того же местоположения с использованием разных значений.

Пример 1. Если вы введете в поиск название места "Lumen Field", то увидите следующую карту:

https://www.google.com/maps/search/?api=1&query=lumen+field

Пример 2. Если вы будете искать стадион "Люмен Фильд", используя только координаты широты и долготы, то увидите следующую карту. Обратите внимание, что на карте есть маркер, но на ней или на боковой панели нет дополнительной информации о месте:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

Пример 3. Поиск стадиона "Люмен Фильд" по географическим координатам и идентификатору места приводит к следующему результату:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

Пример 4. Поиск по названию места "Starbucks" приводит к следующей карте:

https://www.google.com/maps/search/?api=1&query=starbucks

Пример 5. Поиск конкретной кофейни Starbucks по названию и идентификатору места.

https://www.google.com/maps/search/?api=1&query=starbucks&query_place_id=ChIJsU30zM1qkFQRbnOm1_LBoG0

Если вы хотите показать информацию о каком-либо месте, создайте URL поиска в одном из следующих рекомендованных форматов:

• query=PLACE_NAME,ADDRESS
• query=PLACE_NAME&query_place_id=PLACE_ID

Чтобы программно получать идентификаторы мест, можно использовать функции Places API: текстовый поиск(только идентификатор). Это бесплатный способ получения идентификаторов мест. Подробнее об идентификаторе места и запросе к Places API(New).

Идентификаторы мест также можно получить, когда пользователь нажимает на объект инфраструктуры на карте. Подробнее о значках достопримечательностей, на которые можно нажать, рассказывается в статьях о JavaScript, Android и iOS.

Поиск по категориям

При поиске по категориям вы передаете общий поисковый запрос, и Google Карты пытаются найти места, соответствующие вашим критериям, рядом с указанным вами местоположением. Если местоположение не указано, Google Карты попытаются найти предложения рядом с вашим текущим местоположением. Если вы хотите указать местоположение для поиска по категориям, добавьте его в общий поисковый запрос (например, pizza+seattle+wa).

В этом примере при поиске пиццерий в Сиэтле (штат Вашингтон) будет показана следующая карта:

https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa

---

Маршруты

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

Как создать URL маршрута

https://www.google.com/maps/dir/?api=1&parameters

Параметры

• origin – определяет начальную точку маршрута. По умолчанию используется наиболее подходящее начальное местоположение, например местоположение устройства, если оно доступно. Если ни один из вариантов не подходит, на карте может появиться пустая форма, в которой пользователь сможет указать исходную точку. Значение может быть названием места, адресом или координатами по широте и долготе, разделенными запятой. Строка должна быть закодирована для URL, поэтому адрес "City Hall, New York, NY" должен быть преобразован в City+Hall%2C+New+York%2C+NY.

  Примечание. Этот параметр необязательный, если только вы не указали в URL параметр origin_place_id. Если вы решите указать origin_place_id, то в URL также необходимо добавить origin.

• origin_place_id (необязательно). Идентификатор места – это уникальный текстовый идентификатор места. Если вы хотите точно указать заведение, лучше всего использовать идентификатор места. В URL, где используется этот параметр, также должен быть параметр origin.
• destination – определяет конечную точку маршрута. Если значение не задано, на карте может быть показана пустая форма, в которой пользователь сможет указать пункт назначения. Значение может быть названием места, адресом или координатами по широте и долготе, разделенными запятой. Строка должна быть закодирована для URL, поэтому адрес, например "City Hall, New York, NY", следует преобразовать в City+Hall%2C+New+York%2C+NY.

  Примечание. Этот параметр является необязательным, если вы не указали destination_place_id в URL. Если вы решите указать destination_place_id, то в URL также необходимо добавить destination.

• destination_place_id (необязательно). Идентификатор места – это уникальный текстовый идентификатор места. Если вы хотите указать конкретное заведение, используйте идентификатор места. Это гарантирует, что вы сошлетесь на правильное место. URL, в которых используется этот параметр, также должны содержать параметр destination.
• travelmode (необязательно) – определяет способ передвижения. Вот список вариантов:
• driving
• walking – предпочтительны пешеходные дорожки и тротуары (если они есть).
• bicycling – маршруты по велосипедным дорожкам, если они есть. "Велосипед" – это способ передвижения с помощью мускульной силы.
• two-wheeler – маршруты по улицам, где удобнее передвигаться на двухколесном транспорте (если такие есть). Под двухколесными транспортными средствами подразумеваются мотоциклы, скутеры и т. д. Подробнее о маршрутах для двухколесного транспорта…
• transit
Если параметр travelmode не указан, на карте Google показываются один или несколько наиболее подходящих способов передвижения для заданного маршрута и/или предпочтений пользователя.
• dir_action=navigate (необязательно) – запускает пошаговую навигацию или предварительный просмотр маршрута до указанного пункта назначения в зависимости от того, доступна ли начальная точка. Если пользователь укажет начальную точку, которая находится далеко от его текущего местоположения, или если текущее местоположение устройства недоступно, на карте будет показан предварительный просмотр маршрута. Если пользователь не укажет начальную точку (в этом случае по умолчанию будет выбрано текущее местоположение устройства) или она будет находиться недалеко от текущего местоположения пользователя, на карте запустится пошаговая навигация. Обратите внимание, что навигация доступна не во всех продуктах Google Карт и не для всех пунктов назначения. В таких случаях этот параметр будет игнорироваться.
• waypoints – одно или несколько промежуточных мест на маршруте между origin и destination. Несколько промежуточных точек можно указать, разделив их вертикальной чертой (|), например Berlin,Germany|Paris,France. Количество промежуточных точек зависит от платформы, на которой открывается ссылка. В мобильных браузерах поддерживается до трех промежуточных точек, а в остальных случаях – до девяти. Промежуточные точки на карте отображаются в том же порядке, в котором они указаны в URL. Каждая путевая точка может быть указана как название места, адрес или координаты широты и долготы, разделенные запятыми. Строки должны быть закодированы для URL, поэтому такие точки маршрута, как "Берлин, Германия|Париж, Франция", следует преобразовать в Berlin%2CGermany%7CParis%2CFrance.

  Примечания

  • Промежуточные точки не поддерживаются во всех продуктах Google Карт. В таких случаях этот параметр будет игнорироваться.
  • Этот параметр необязателен, если только вы не указали в URL параметр waypoint_place_ids. Если вы решите указать waypoint_place_ids, то в URL также нужно будет добавить waypoints.
• waypoint_place_ids (необязательно). Идентификатор места – это уникальный текстовый идентификатор места. Waypoint_place_ids позволяет указать список идентификаторов мест, которые будут сопоставлены со списком waypoints. Идентификаторы мест должны быть перечислены в том же порядке, что и точки маршрута, и разделены вертикальной чертой "|" ( в кодировке URL – %7C). Если вы хотите точно указать определенные заведения, идентификаторы мест – лучший способ это сделать. URL, в которых используется этот параметр, также должны содержать waypoints.
• avoid (необязательный параметр). Задает объекты, которых маршрут должен по возможности избегать. Можно указать один или несколько вариантов, разделенных запятой , ( в кодировке URL – %2C):
  • ferries
  • highways
  • tolls

Примеры маршрутов

Следующий URL-адрес запускает карту в режиме маршрутов и предоставляет форму, позволяющую пользователю ввести пункт отправления и пункт назначения.

https://www.google.com/maps/dir/?api=1

В следующем примере запускается карта с велосипедным маршрутом от башни Спейс-Нидл до рынка Пайк-Плейс-маркет в Сиэтле (штат Вашингтон, США).

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

В следующем примере показано, как запустить карту с маршрутом для двухколесного транспорта от офиса Google в Мумбаи до международного аэропорта Мумбаи.

https://www.google.com/maps/dir/?api=1&origin=Google+Mumbai+India&destination=Mumbai+Airport&travelmode=two-wheeler

В следующем примере запускается карта с пешеходным маршрутом от офиса Google в Сиднее (Австралия) до здания королевы Виктории.

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking

Отображение карты

Действие "Карта" возвращает карту без маркеров и маршрутов.

Как создать URL карты

https://www.google.com/maps/@?api=1&map_action=map&parameters

Параметры

• map_action=map (обязательно) – тип карты. У Карт и Просмотра улиц одна конечная точка. Чтобы карта отображалась, для параметра map_action должно быть задано значение map.
• center (необязательный параметр). Определяет центр окна карты и принимает координаты широты и долготы в виде значений, разделенных запятыми (например, -33.8569,151.2152).
• zoom (необязательно) – задает начальный уровень масштабирования карты. Допустимые значения – целые числа от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных для выбранного местоположения. Значение по умолчанию: 15.
• basemap (необязательно) – определяет тип карты для показа. Значение может быть roadmap (по умолчанию), satellite или terrain.
• layer (необязательно) – определяет дополнительный слой, который будет отображаться на карте, если он есть. Значение может быть одним из следующих: none (по умолчанию), transit, traffic или bicycling.

Примеры карт

В этом примере URL запускает стандартную карту Google, центрированную по текущему местоположению пользователя.

https://www.google.com/maps/@?api=1&map_action=map

В примере ниже показана карта с центром в Катумбе (Новый Южный Уэльс, Австралия) с координатами -33.712206,150.311941 и заданными необязательными параметрами zoom и basemap.

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain

---

Как показать панораму в Просмотре улиц

Действие pano позволяет запустить средство просмотра, чтобы показывать изображения Просмотра улиц в виде интерактивных панорам. Каждая панорама в Просмотре улиц представляет собой изображение или набор изображений, которые обеспечивают полный круговой обзор из одной точки. Изображения содержат 360-градусный горизонтальный обзор (полный оборот) и 180-градусный вертикальный обзор (от направления строго вверх до направления строго вниз). Действие pano запускает средство просмотра, которое отображает панораму в виде сферы с камерой в центре. Вы можете управлять масштабом и ориентацией камеры.

Google Просмотр улиц – это сервис, предоставляющий доступ к панорамам множества разных мест по всему миру. Также доступны фотосферы, добавленные пользователями, и специальные коллекции Просмотра улиц.

Как создать URL Просмотра улиц

https://www.google.com/maps/@?api=1&map_action=pano&parameters

Параметры

• map_action=pano (обязательно) – указывает тип представления, которое нужно показать. Maps и Просмотр улиц используют одну и ту же конечную точку. Чтобы панорама отображалась, action должен быть указан как pano.

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

• viewpoint – зритель показывает панораму, снятую ближе всего к местоположению viewpoint, которое задается в виде координат широты и долготы, разделенных запятой (например, 46.414382,10.013988). Поскольку изображения Просмотра улиц периодически обновляются и фотографии могут быть сделаны с немного разных позиций, при обновлении изображений ваше местоположение может быть привязано к другой панораме.
• pano: идентификатор панорамы изображения, которое нужно показать. Если вы задали значение pano, то можете также указать значение viewpoint. Параметр viewpoint используется только в том случае, если Google Картам не удается найти идентификатор панорамы. Если правило pano задано, но не найдено, а правило viewpoint НЕ задано, панорамное изображение не показывается. Вместо этого Google Карты откроются в режиме по умолчанию, и на экране будет показана карта с центром в текущем местоположении пользователя.

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

• heading – направление камеры по компасу в градусах по часовой стрелке от севера. Допустимые значения: от -180 до 360 градусов. Если этот параметр не задан, направление выбирается по умолчанию на основе точки обзора (если она указана) и фактического местоположения изображения.
• pitch – угол наклона камеры вверх или вниз. Угол наклона указывается в градусах от -90 до 90. Положительные значения наклоняют камеру вверх, а отрицательные – вниз. Угол наклона по умолчанию (0) задается на основе положения камеры во время съемки. Поэтому угол наклона, равный 0, часто, но не всегда, является горизонтальным. Например, при съемке панорамы на холме угол наклона по умолчанию, скорее всего, не будет горизонтальным.
• fov – определяет горизонтальную зону обзора изображения. Угол обзора указывается в градусах и может составлять от 10 до 100. По умолчанию установлено значение 90. При работе с областью просмотра фиксированного размера поле зрения считается уровнем масштабирования, при этом меньшие числа указывают на более высокий уровень масштабирования.

Примеры Просмотра улиц

В первых двух примерах показана панорама Эйфелевой башни. В первом примере для указания местоположения используется только параметр viewpoint, а также заданы необязательные параметры heading, pitch и fov. Для сравнения во втором примере используется идентификатор pano и те же параметры, что и в первом примере. В третьем примере показана панорама помещения.

Пример 1. Для указания местоположения используется только свойство viewpoint.

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

Пример 2. Используется идентификатор pano и местоположение viewpoint. Идентификатор pano имеет приоритет над viewpoint. В этом примере идентификатор панорамы найден, поэтому элемент viewpoint игнорируется. Обратите внимание, что панорамное изображение, которое отображается для идентификатора pano, немного отличается от изображения, найденного только с помощью viewpoint, и является более новым.

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

Пример 3. Показывает панораму интерьера ресторана Sarastro в Лондоне (Великобритания), указанную с помощью идентификатора панорамы.

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

Как найти идентификатор панорамы

Найти идентификатор определенной панорамы можно несколькими способами.

• В JavaScript используйте класс StreetViewPanorama.
• Для Android используйте общедоступный класс StreetViewPanoramaLocation.
• Для iOS используйте класс GMSPanorama.
• Вы также можете отправлять запросы метаданных с помощью Google Просмотр улиц Image API. Запросы метаданных изображений предоставляют данные о панорамах в Просмотре улиц, включая идентификатор панорамы.

Другие примеры

Примеры маршрутов с путевыми точками

В приведенных ниже примерах запускаются Google Карты и показываются маршруты для автомобилей из Парижа (Франция) в Шербур (Франция) с промежуточными точками:

Город, страна	Название места	Идентификатор места
1. Версаль, Франция	Версальский дворец	ChIJdUyx15R95kcRj85ZX8H8OAU
2. Шартр, Франция	Шартрский собор	ChIJKzGHdEgM5EcR_OBTT3nQoEA
3. Ле-Ман, Франция	Собор Святого Юлиана Ле-Манского	ChIJG2LvQNCI4kcRKXNoAsPi1Mc
4. Кан, Франция	Канский замок	ChIJ06tnGbxCCkgRsfNjEQMwUsc

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

Пример 1. Опорные точки определены как город и страна:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

Пример 2. Путевые точки заданы как названия мест:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

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

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

Пример 4. Путевые точки определяются как "Город, Страна", но перечислены в другом порядке по сравнению с предыдущими примерами. Демонстрирует, что на карте путевые точки отображаются в том порядке, в котором они перечислены в URL.

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

Примеры карт

Отображает карту с указанными параметрами basemap (спутник) и layer (общественный транспорт).

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

Примеры Просмотра улиц

Показывает панораму в Просмотре улиц, используя ключ изображения FIFE в качестве идентификатора pano. Обратите внимание, что перед идентификатором pano указано F:.

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55

Как улучшить URL Карт с помощью параметров UTM

Чтобы помочь Google понять, как разработчики интегрируют URL Карт, и обеспечить оптимальную производительность, мы рекомендуем добавлять в URL параметры отслеживания UTM. Добавив параметры utm_source и utm_campaign, вы предоставите нам ценные данные, которые помогут анализировать модели использования и улучшать продукт "URL Карт".

Для параметра utm_source используйте название приложения. Параметр utm_campaign должен отражать намерение пользователя, например "location_sharing" (предоставление доступа к местоположению), "place_details_search" (поиск информации о месте) или "directions_request" (запрос маршрута).

Например, URL с параметрами UTM может выглядеть так:

https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YOUR_APP_NAME&utm_campaign=place_details_search