Введение
Используя URL-адреса Google Maps, вы можете создать универсальный кроссплатформенный URL-адрес для запуска Google Maps , выполнения поиска, получения указаний и навигации, а также отображения карт и панорамных изображений. Синтаксис URL-адреса одинаков независимо от используемой платформы.
Для использования URL-адресов Картов вам не нужен ключ API Google.
Универсальный кроссплатформенный синтаксис
Разработчик Android-приложения, iOS-приложения или веб-сайта может создать общий URL-адрес, который откроет Google Maps и выполнит запрошенное действие независимо от платформы, используемой при открытии карты.
- На устройстве Android:
- Если приложение Google Maps для Android установлено и активно, URL-адрес запускает Google Maps в приложении «Карты» и выполняет запрошенное действие.
- Если приложение Google Maps не установлено или отключено, URL-адрес запускает Google Maps в браузере и выполняет запрошенное действие.
- На устройстве iOS:
- Если установлено приложение Google Maps для iOS , URL-адрес запускает Google Maps в приложении «Карты» и выполняет запрошенное действие.
- Если приложение Google Maps не установлено, URL-адрес запускает Google Maps в браузере и выполняет запрошенное действие.
- На любом другом устройстве URL-адрес запускает Google Maps в браузере и выполняет запрошенное действие.
Рекомендуется использовать кроссплатформенный URL-адрес для запуска Google Maps из вашего приложения или веб-сайта, поскольку такие универсальные URL-адреса позволяют обрабатывать запросы к картам независимо от используемой платформы. Для функций, которые могут быть доступны только на мобильных платформах (например, пошаговая навигация), вы можете предпочесть использовать вариант, специфичный для платформы Android или iOS. См. следующую документацию:
- Интенты Google Maps для Android — специально для запуска приложения Google Maps для Android.
- Схема URL-адресов Google Maps для iOS — специально для запуска приложения Google Maps для iOS.
Запуск Google Maps и выполнение определённого действия.
Для запуска Google Maps и, при необходимости, выполнения одной из поддерживаемых функций используйте URL-адрес одного из следующих типов в зависимости от запрашиваемого действия:
- Поиск — запустите карту Google, которая отобразит метку определенного места, или выполните общий поиск и запустите карту для отображения результатов:
https://www.google.com/maps/search/?api=1 & parameters - Запрос маршрута — запросите маршрут и запустите Google Maps с полученными результатами:
https://www.google.com/maps/dir/?api=1 & parameters - Отобразить карту — запустить Google Maps без маркеров и указаний:
https://www.google.com/maps/@?api=1&map_action=map & parameters - Отобразить панораму Street View — запустить интерактивное панорамное изображение:
https://www.google.com/maps/@?api=1&map_action=pano & parameters
Важно : Параметр api=1 определяет версию URL-адресов Google Maps, для которой предназначен данный URL. Этот параметр обязателен в каждом запросе. Единственное допустимое значение — 1. Если api=1 отсутствует в URL, все параметры игнорируются, и запускается стандартное приложение Google Maps, либо в браузере, либо в мобильном приложении Google Maps, в зависимости от используемой платформы (например, https://www.google.com/maps ).
Создание допустимых URL-адресов
Необходимо правильно закодировать URL-адреса.
Например, некоторые параметры используют символ вертикальной черты ( | ) в качестве разделителя, который необходимо закодировать как %7C в итоговом URL-адресе. Другие параметры используют значения, разделенные запятыми, такие как координаты широты/долготы или город, штат. Запятую необходимо закодировать как %2C . Пробелы кодируйте как %20 или заменяйте их знаком плюс ( + ).
Кроме того, длина URL-адресов ограничена 2048 символами на каждый запрос. Учитывайте это ограничение при составлении URL-адресов.
Действия на карте
Доступные действия на карте: поиск, построение маршрута, отображение карты и отображение панорамы Street View. Действие указывается в URL-адресе запроса вместе с обязательными и необязательными параметрами. Как это принято в URL-адресах, параметры разделяются символом амперсанда ( & ). Для каждого действия список параметров и их возможных значений приведен в разделе «Параметры поиска» .
Поиск
Функция поиска отображает результаты поиска по видимой области карты. При поиске конкретного места на карте устанавливается метка в указанной точке и отображается подробная информация о доступных местах.
Формирование URL-адреса поиска
https://www.google.com/maps/search/?api=1 & parametersПараметры
-
query(обязательно): Определяет места, которые следует выделить на карте. Параметр query обязателен для всех поисковых запросов.- Указывайте местоположение в виде названия места, адреса или координат широты/долготы, разделенных запятыми. Строки должны быть закодированы в формате URL , поэтому адрес, например, "City Hall, New York, NY", следует преобразовать в
City+Hall%2C+New+York%2C+NY. - Укажите общие поисковые запросы в виде строки, закодированной в формате URL , например,
grocery+storesилиrestaurants+in+seattle+wa.
- Указывайте местоположение в виде названия места, адреса или координат широты/долготы, разделенных запятыми. Строки должны быть закодированы в формате URL , поэтому адрес, например, "City Hall, New York, NY", следует преобразовать в
-
query_place_id(необязательно): Идентификатор места — это текстовый идентификатор, который однозначно определяет место. Дляsearchнеобходимо указатьquery, но можно также указатьquery_place_id. Если указаны оба параметра,queryбудет использоваться только в том случае, если Google Maps не сможет найти идентификатор места. Если вы пытаетесь точно указать ссылку на конкретное заведение, идентификатор места — лучшая гарантия того, что вы укажете правильное место. Также рекомендуется указыватьquery_place_idпри поиске конкретного местоположения с использованием координат широты/долготы.
Примеры поиска
Поиск по местоположению
При поиске по местоположению вы ищете конкретное место, используя название места, адрес или координаты широты и долготы, разделенные запятыми, и на полученной карте отображается метка в этом месте. Эти три примера иллюстрируют поиск одного и того же места с использованием разных значений местоположения.
Пример 1: Поиск по названию места "Lumen Field" приводит к следующей карте:
https://www.google.com/maps/search/?api=1&query=lumen+field

Пример 2: Поиск Lumen Field с использованием только координат широты/долготы приводит к следующей карте. Обратите внимание, что на карте есть метка, но дополнительная информация о местоположении на карте или в боковой панели отсутствует:
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

Пример 3: Поиск Lumen Field с использованием координат широты/долготы, а также идентификатора места приводит к следующей карте:

Пример 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
Для программного получения идентификаторов мест можно использовать функции текстового поиска (только идентификатор) API мест . Это бесплатный способ получения идентификаторов мест. Узнайте больше об идентификаторах мест и запросах API мест (новых) .
Идентификаторы мест также можно получить, когда пользователь щелкает или касается объекта интереса на карте. Подробнее о кликабельных значках объектов интереса можно узнать здесь ( JavaScript , Android , iOS ).
Категориальный поиск
При поиске по категориям вы указываете общий поисковый запрос, и Google Maps пытается найти объявления, соответствующие вашим критериям, рядом с указанным вами местоположением. Если местоположение не указано, Google Maps пытается найти объявления рядом с вашим текущим местоположением. Если вы предпочитаете указать местоположение для поиска по категориям, включите его в общую поисковую строку (например, 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.Примечание : Этот параметр является необязательным, если вы не укажете
origin_place_idв своем URL-адресе. Если вы решите указатьorigin_place_id, вам также необходимо включитьoriginв URL-адрес. -
origin_place_id(необязательно): Идентификатор места — это текстовый идентификатор, который однозначно определяет место. Если вы хотите точно указать конкретное заведение, использование идентификатора места — лучшая гарантия того, что вы создадите ссылку на нужное место. URL-адреса, использующие этот параметр, также должны включатьorigin. -
origin_nav_point_token(необязательно): Токен точки навигации пункта отправления. Токен точки навигации представляет собой конкретную физическую точку доступа к пункту отправления (например, конкретный вход, зону погрузки или погрузочную площадку), а не все местоположение целиком. Если он присутствует, другие параметры пункта отправления (такие какoriginиorigin_place_id) будут игнорироваться. Для получения дополнительной информации о токенах точек навигации и способах их получения см. раздел «Маршрутизация с использованием токенов точек навигации» . -
destination: Определяет конечную точку маршрута. Если конечная точка отсутствует, на карте может отображаться пустая форма для ввода адреса назначения пользователем. Значение может быть либо названием места, адресом, либо координатами широты и долготы, разделенными запятыми. Строка должна быть закодирована в формате URL , поэтому адрес, например, "City Hall, New York, NY", должен быть преобразован вCity+Hall%2C+New+York%2C+NY.Примечание : Этот параметр является необязательным, если вы не укажете
destination_place_idв своем URL-адресе. Если вы решите указатьdestination_place_id, вам также необходимо включитьdestinationв URL-адрес. -
destination_place_id(необязательно): Идентификатор места — это текстовый идентификатор, который однозначно определяет место. Если вы хотите точно указать конкретное заведение, использование идентификатора места — лучшая гарантия того, что вы получите ссылку на нужное место. URL-адреса, использующие этот параметр, также должны включатьdestination. -
destination_nav_point_token(необязательно): Токен точки навигации пункта назначения. Токен точки навигации представляет собой конкретную физическую точку доступа к пункту назначения (например, конкретный вход, зону посадки или погрузочную площадку), а не все местоположение целиком. Если он присутствует, другие параметры пункта назначения (такие какdestinationиdestination_place_id) будут игнорироваться. Для получения дополнительной информации о токенах точек навигации и способах их получения см. раздел «Маршрутизация с использованием токенов точек навигации» . -
travelmode(необязательно): Определяет способ передвижения. Вот список вариантов: -
driving -
walking: предпочитает пешеходные дорожки и тротуары, где это возможно. -
bicycling: маршруты по велосипедным дорожкам, если таковые имеются. «Велосипед» означает способ передвижения с использованием мускульной силы человека. -
two-wheeler: Маршруты по предпочтительным улицам для двухколесных транспортных средств, где это возможно. «Двухколесное транспортное средство» относится к двухколесным моторизованным транспортным средствам, таким как мотоциклы. Для получения дополнительной информации см. раздел «Покрытие для двухколесных транспортных средств ». -
transit -
dir_action=navigate(необязательно): Запускает либо пошаговую навигацию, либо предварительный просмотр маршрута до указанного пункта назначения в зависимости от доступности начальной точки. Если пользователь указывает начальную точку, и она находится далеко от его текущего местоположения, или текущее местоположение устройства недоступно, карта запускает предварительный просмотр маршрута. Если пользователь не указывает начальную точку (в этом случае начальная точка по умолчанию устанавливается в соответствии с текущим местоположением устройства), или начальная точка находится близко к его текущему местоположению, карта запускает пошаговую навигацию. Обратите внимание, что навигация доступна не во всех продуктах Google Maps и/или между всеми пунктами назначения; в этих случаях этот параметр будет проигнорирован. -
waypoints: Указывает одно или несколько промежуточных мест, через которые прокладывается маршрут междуoriginиdestination. Можно указать несколько путевых точек, разделяя их символом вертикальной черты (|) (например,Berlin,Germany|Paris,France). Количество разрешенных путевых точек зависит от платформы, на которой открывается ссылка: до трех путевых точек поддерживаются в мобильных браузерах, а в остальных — максимум девять. Путевые точки отображаются на карте в том же порядке, в котором они указаны в URL-адресе. Каждая путевая точка может быть названием места, адресом или координатами широты/долготы, разделенными запятыми. Строки должны быть закодированы в формате URL , поэтому путевые точки, такие как "Berlin,Germany|Paris,France", должны быть преобразованы вBerlin%2CGermany%7CParis%2CFrance.Примечания :
- Функция указания путевых точек поддерживается не во всех продуктах Google Maps; в таких случаях этот параметр будет проигнорирован.
- Этот параметр является необязательным, если вы не укажете
waypoint_place_idsв своем URL-адресе. Если вы решите указатьwaypoint_place_ids, вам также необходимо включитьwaypointsв URL-адрес.
-
waypoint_place_ids(необязательно): Идентификатор места — это текстовый идентификатор, который однозначно определяет место.Waypoint_place_idsпозволяет указать список идентификаторов мест, соответствующих спискуwaypoints. Идентификаторы мест должны быть перечислены в том же порядке, что и путевые точки, и разделены символом вертикальной черты "|" ( в URL-кодировке как%7C). Если вы пытаетесь однозначно указать определенные заведения, идентификаторы мест — лучшая гарантия того, что вы получите ссылку на правильные места. URL-адреса, использующие этот параметр, также должны включатьwaypoints. -
waypoint_nav_point_tokens(необязательно): Список токенов навигационных точек для промежуточных путевых точек. Токен навигационной точки представляет собой конкретную физическую точку доступа (например, конкретный вход, зону посадки или погрузочную площадку), а не все местоположение целиком. Должен представлять собой список записей, разделенных символом вертикальной черты ("|") ( закодированный в URL как%7C), и должен иметь ту же длину, что иwaypoints. Если токен присутствует для путевой точки вwaypoint_nav_point_tokens, значения с тем же индексом вwaypointsиwaypoint_place_idsбудут игнорироваться. Для получения дополнительной информации о токенах навигационных точек и способах их получения см. раздел «Маршрутизация с использованием токенов навигационных точек» . -
avoid(необязательно): Задает параметры, которые маршрут должен попытаться обойти. Может быть задан один или несколько из следующих вариантов, разделенных запятой "," ( URL-кодировка :%2C):-
ferries -
highways -
tolls
-
travelmode не указан, на карте Google отображается один или несколько наиболее подходящих способов передвижения для указанного маршрута и/или предпочтений пользователя.Примеры инструкций
По указанному ниже URL-адресу открывается карта в режиме построения маршрута, а также форма, позволяющая пользователю ввести начальную и конечную точки маршрута.
https://www.google.com/maps/dir/?api=1

В следующем примере запускается карта с маршрутом для велосипедистов от башни Space Needle до рынка Pike Place Market в Сиэтле, штат Вашингтон.

В следующем примере запускается карта с маршрутом для двухколесного транспорта от Google Мумбаи до международного аэропорта Мумбаи.
.
В следующем примере запускается карта с пешеходным маршрутом от Google Сиднея, Австралия, до здания Queen Victoria Building.

Отображение карты
Действие «Карта» возвращает карту без маркеров и указаний.
Формирование URL-адреса карты
https://www.google.com/maps/@?api=1&map_action=map & parametersПараметры
-
map_action=map(обязательно): Указывает тип отображаемой карты. Карты и Street View используют одну и ту же конечную точку. Чтобы гарантировать отображение карты,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 .

Отображение панорамы Street View
Действие «Панорама» позволяет запустить средство просмотра, отображающее изображения Street View в виде интерактивных панорам. Каждая панорама Street View обеспечивает полный 360-градусный обзор из одной точки. Изображения содержат 360 градусов горизонтального обзора (полный круговой обзор) и 180 градусов вертикального обзора (от вертикального положения вверх до вертикального положения вниз). Действие «Панорама» запускает средство просмотра, которое отображает полученную панораму в виде сферы с камерой в центре. Вы можете управлять камерой, чтобы контролировать масштабирование и ориентацию камеры.
Google Street View предоставляет панорамные виды из специально обозначенных мест по всей зоне покрытия . Также доступны фотографии, созданные пользователями , и специальные коллекции Street View .
Формирование URL-адреса Street View
https://www.google.com/maps/@?api=1&map_action=pano & parametersПараметры
-
map_action=pano(обязательно): Указывает тип отображаемого вида. Карты и Street View используют одну и ту же конечную точку. Чтобы гарантировать отображение панорамы,actionдолжно быть указано какpano.
Также требуется один из следующих параметров URL:
-
viewpoint: В окне просмотра отображается панорама, снятая с ближайшего к точкеviewpointместоположения, указанного в виде координат широты и долготы, разделенных запятыми (например, 46.414382,10.013988). Поскольку изображения Street View периодически обновляются, и фотографии могут быть сделаны с немного разных позиций каждый раз, возможно, что при обновлении изображений ваше местоположение может автоматически отобразить другую панораму. -
pano: Конкретный идентификатор панорамы для отображения изображения. Если вы указываетеpanoвы также можете указатьviewpoint.viewpointиспользуется только в том случае, если Google Maps не может найти идентификатор панорамы. Еслиpanoуказана, но не найдена, иviewpointНЕ указана, панорамное изображение не отображается. Вместо этого Google Maps открывается в режиме по умолчанию, отображая карту, центрированную на текущем местоположении пользователя.
Следующие параметры URL являются необязательными:
-
heading: указывает направление камеры по компасу в градусах по часовой стрелке от севера. Допустимые значения от -180 до 360 градусов. Если параметр опущен, выбирается направление по умолчанию на основе точки обзора (если указана) запроса и фактического местоположения изображения. -
pitch: Задает угол наклона камеры — вверх или вниз. Угол наклона задается в градусах от -90 до 90. Положительные значения будут наклонять камеру вверх, а отрицательные — вниз. Угол наклона по умолчанию, равный 0, устанавливается на основе положения камеры в момент съемки. Поэтому угол наклона, равный 0, часто, но не всегда, является горизонтальным. Например, изображение, сделанное на холме, скорее всего, будет иметь угол наклона по умолчанию, который не будет горизонтальным. -
fov: Определяет горизонтальное поле зрения изображения. Поле зрения выражается в градусах, диапазон значений от 10 до 100. По умолчанию — 90. При работе с окном просмотра фиксированного размера поле зрения считается уровнем масштабирования, при этом меньшие числа указывают на более высокий уровень масштабирования.
Примеры Street View
Первые два примера демонстрируют панораму Эйфелевой башни. В первом примере используется только точка viewpoint , а также задаются необязательные параметры heading , pitch и fov . Для сравнения, во втором примере используется идентификатор pano , а также те же параметры, что и в первом примере. В третьем примере отображается панорамное изображение помещения.
Пример 1: Для указания местоположения используется только viewpoint .

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

Пример 3: Отображает панораму интерьера ресторана Sarastro в Лондоне, Великобритания, с указанием идентификатора панорамы.
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

Поиск идентификатора панорамы
Для определения идентификатора конкретного панорамного изображения можно использовать несколько методов.
- Для JavaScript используйте класс StreetViewPanorama .
- Для Android используйте публичный класс StreetViewPanoramaLocation .
- Для iOS используйте класс GMSPanorama .
- Вы также можете отправлять запросы на метаданные, используя API изображений Google Street View . Запросы на метаданные изображений предоставляют информацию о панорамах Street View, включая идентификатор панорамы.
Больше примеров
Примеры построения маршрута с использованием путевых точек.
Приведенные ниже примеры маршрутов запускают Google Maps и отображают автомобильный маршрут из Парижа (Франция) в Шербур (Франция), проходящий через следующие промежуточные точки:
| Город, Страна | Название места | Идентификатор места |
|---|---|---|
| 1. Версаль, Франция | Версальский дворец | ChIJdUyx15R95kcRj85ZX8H8OAU |
| 2. Шартр, Франция | Шартрский собор | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
| 3. Ле-Ман, Франция | Собор Святого Юлиана в Ле-Мане | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
| 4. Кан, Франция | Замок Кан | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
В приведенных примерах URL-адресов путевые точки определены по-разному, поэтому вы можете сравнить различия в отображении путевых точек на результирующих картах.
Пример 1: Путевые точки определены как Город, Страна:

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

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

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

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

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

Улучшение URL-адресов карт с помощью UTM-параметров
Чтобы помочь Google лучше понять, как разработчики интегрируют URL-адреса Карты, и обеспечить оптимальную производительность, мы рекомендуем включать параметры отслеживания UTM в структуру ваших URL-адресов. Добавление параметров 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