Направляйте пользователей к сведениям о местах и ​​маршрутам на Картах Google с помощью URL-адреса Карт или API мест.

В современном мире, ориентированном на местоположение, пользователи ожидают бесперебойного доступа к информации о месте, направлениям и навигации. Будь то приложение-мессенджер, приложение для обнаружения локального контекста, логистическая и транспортная платформа, планировщик путешествий или платформа листинга недвижимости, пользователям часто нужно быстро просмотреть сведения о местоположении или найти лучший маршрут из пункта А в пункт Б. Хотя разработчики могут создавать собственный опыт в приложении, использование всеобъемлющего и знакомого интерфейса Google Maps обеспечивает превосходный опыт.

Хорошо структурированный URL-адрес Google Maps необходим для бесперебойного пользовательского опыта. Неправильные URL-адреса ухудшают этот опыт, направляя пользователей в неправильное местоположение, отображая общий вид карты вместо конкретных деталей или даже приводя к неработающей ссылке. Это расстраивает пользователей и не позволяет им достичь своей цели. Например, даже при наличии действительного URL-адреса Карт пользователь, ожидающий подробностей о конкретной компании, может вместо этого попасть на общий вид карты без какой-либо релевантной информации. Смотрите пример ниже:

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152

Этот URL-адрес Карт действителен для открытия Google Карт и отображения местоположения на основе широты и долготы. Однако он не предоставляет пользователям сведения о конкретном месте.

Поиск только по широте и долготе
Поиск только по широте и долготе

Простая связь вашего приложения с Google Maps с помощью точных URL-адресов

Открыть страницу сведений о месте на Google Maps
URL-адрес Карт с уникальным названием места перенаправляет пользователей на страницу с подробностями этого места на Картах Google.

Google Maps Platform (GMP) предлагает два основных метода для построения точных URL-адресов: Places API (новый), который требует ключа API, и Maps URL-адреса, которые бесплатны и не требуют ключа. Следующие решения охватывают различные сценарии и варианты использования:

API GMP Places (новый) возвращает полный набор информации о конкретном месте. При запросе поля googleMapsUri или googleMapsLinks (указав его в маске поля ) ответ API включает объект места. Этот объект содержит предварительно отформатированные URL-адреса, которые можно использовать для непосредственного открытия соответствующего представления, например представления сведений о месте, в Картах Google.

Пример:

Запросить информацию о месте

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
-H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \
https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE

Ответ на вопрос о месте:

{
    "googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
    "googleMapsLinks": {
        "directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
        "placeUri": "https://maps.google.com/?cid=3545450935484072529",
        "writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
        "reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
        "photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
    }
}

ChIJ3S-JXmauEmsRUcIaWtf4MzE в приведенном выше примере — это идентификатор места Сиднейского оперного театра в приведенном выше примере. Идентификатор места — это текстовый идентификатор, который однозначно идентифицирует место в базе данных Google Places и на Google Maps.

Получение идентификаторов мест с нулевой стоимостью

Для программного получения идентификаторов мест можно использовать API мест: функциональность Text Search(ID Only) . Это метод получения идентификаторов мест с нулевыми затратами. Узнайте больше о Place ID и запросе API мест (New) .

Запрос на текстовый поиск API Places (только идентификатор):

curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Ответ текстового поиска API Places (только идентификатор):

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

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

Выполнение

При использовании API Places разработчики могут просто извлечь поле googleMapsUri или googleMapsLinks из ответа и использовать его для запуска соответствующего представления в приложении Google Maps или в браузере, если приложение не установлено.

Особенность Описание
направленияUri Ссылка для открытия Google Maps для отображения маршрутов от текущего местоположения пользователя до этого места
местоUri Ссылка для открытия Карт Google на странице сведений об этом месте
writeAReviewUri Ссылка для открытия Карт Google на страницу написания отзыва об этом месте
отзывыUri Ссылка для открытия Карт Google на странице отзывов об этом месте
фотоUri Ссылка для открытия Карт Google на странице фотографий этого места

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

Использование URL-адресов Карт

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

Доступны следующие действия на карте:

  • Функция поиска запускает приложение Google Maps или в браузере, если приложение не установлено, отображает метку определенного места или выполняет общий поиск и запускает карту для отображения результатов.

  • Функция «Маршруты» запускает приложение Google Maps или браузер, если приложение не установлено, которое отображает маршруты между точками или включает пошаговую навигацию на Google Maps для мобильных устройств.

  • Функция панорамы Street View позволяет запустить просмотрщик для отображения изображений Street View в виде интерактивных панорам.

Посетите документацию разработчика URL-адресов GMP Maps, чтобы изучить дополнительные функции и примеры.

Здесь мы рассмотрим две ключевые функции URL-адресов Карт:

  • Отображение сведений о месте на Картах Google: В этом разделе объясняется, как создавать URL-адреса, которые будут отображать сведения о конкретном месте на Картах Google. Также подробно описывается, как работать с местами, имеющими неуникальные названия, используя идентификаторы мест и точные запросы.

  • Предоставление маршрутов с использованием URL-адресов Карт: в этом разделе объясняется, как создавать URL-адреса, предоставляющие маршруты между локациями, включая маршруты с несколькими путевыми точками и пошаговую навигацию.

Отображение сведений о месте на Google Maps

Функция поиска принимает два параметра для выполнения поиска мест: query (обязательный) и query_place_id (необязательный).

Параметр query обязателен для всех поисковых запросов. Он принимает название места, или координаты широты/долготы, разделенные запятыми, или общий поисковый термин.

Структура URL поиска:

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

Сценарий 1: Отображение сведений о месте для уникального названия места

https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
 В этом примере указано только название места. Этот URL открывает страницу с подробностями о Сиднейском оперном театре.

Открыть страницу сведений о месте на Google Maps
Поиск названия места и отображение сведений о месте

Теперь рассмотрим место с неуникальным названием. Что произойдет, если вы выполните поиск только по этому неуникальному названию? Смотрите следующий сценарий.

Сценарий 2: Поиск мест по неуникальному названию места

https://www.google.com/maps/search/?api=1&query=7-Eleven

Поскольку название места не уникально, этот URL открывает список близлежащих магазинов 7-Eleven в области просмотра. Затем пользователи могут выбрать конкретный магазин, чтобы просмотреть его данные.

Открыть страницу списка мест на Google Maps
Страница списка мест для поиска неуникального имени

Чтобы избежать списка местоположений и напрямую перейти на определенную страницу с подробностями, можно использовать более точный метод. Смотрите следующий пример.

Сценарий 3: Отображение сведений о месте с неуникальным названием

При работе с общими названиями мест простой поиск по названию часто возвращает список местоположений. Чтобы напрямую перейти на страницу с конкретными данными, можно использовать один из следующих методов:

Метод 1: Использование точного запроса с названием места и адресом

https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia

В этом URL-адресе параметр query отформатирован как название места, адрес. Это помогает сузить поиск и напрямую перейти к предполагаемому местоположению.

Метод 2: Использование идентификатора места

Идентификаторы мест однозначно идентифицируют место в базе данных Google Places и на Картах Google. 

https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM

Здесь ChIJGcmcg7ZC1moRAOacd3HoEwM — уникальный идентификатор места для определенного места. Параметр query по-прежнему требуется, но будет использоваться только в том случае, если Google Maps не сможет найти идентификатор места.

Сценарий 4: Отображение сведений о месте с использованием координат широты и долготы, а также идентификатора места

Использование идентификатора места гарантирует, что Google Maps отображает подробную информацию о месте. 

https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
Страница сведений о месте с указанием широты и долготы, а также идентификатора места
Страница сведений о месте с указанием широты и долготы, а также идентификатора места

Получение идентификаторов мест с нулевой стоимостью

Для программного получения идентификаторов мест можно использовать API мест: функциональность Text Search(ID Only) . Это метод получения идентификаторов мест с нулевыми затратами. Узнайте больше о запросе Place ID и API мест (New) .

Запрос на текстовый поиск API Places (только идентификатор): 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Ответ текстового поиска API Places (только идентификатор): 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

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

Заключение

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

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

Избегайте использования только координат широты/долготы в параметре query , когда ваша цель — отобразить сведения о конкретном месте. Такие форматы, как query=latitude,longitude , query=PLACE_NAME,latitude,longitude или query=ADDRESS,latitude,longitude не всегда приведут к нужной странице сведений о месте. Вместо этого будут показаны широта и долгота местоположения.

Категориальный поиск с использованием URL-адресов Карт

В категориальном поиске вы передаете общий поисковый запрос, и Google Maps пытается найти списки, которые соответствуют вашим критериям, рядом с указанным вами местоположением. Если местоположение не указано, Google Maps пытается найти списки рядом с вашим текущим местоположением.

Сценарий 1: Поиск близлежащих мест 

https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
Категориальный поиск - близлежащие места
Категориальный поиск - близлежащие места

Предоставление маршрутов с использованием URL-адресов Карт

Функция Directions отображает путь между двумя или более указанными точками на карте, а также расстояние и время в пути. Она предоставляет разработчикам больше контроля над предоставляемыми направлениями. Документация GMP Maps URLs Directions содержит подробные инструкции по построению URL для настраиваемых направлений.

Структура URL-адреса маршрута: 

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

Сценарий 1: Поиск наилучшего маршрута от текущего местоположения пользователя до пункта назначения 

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving

Этот URL-адрес открывает Google Maps и отображает маршрут проезда из текущего местоположения пользователя.

В этом URL-адресе origin опущен. Если origin опущен, путь по умолчанию соответствует наиболее релевантному начальному местоположению, например местоположению устройства, если оно доступно. Если его нет, то полученная карта предоставляет форму, позволяющую пользователю ввести источник. Значением источника и назначения может быть либо название места, адрес, либо координаты широты/долготы, разделенные запятыми.

travelmode — необязательный параметр. Он определяет способ передвижения. Этот параметр можно задать как:

  • вождение
  • ходьба
  • езда на велосипеде
  • двухколесный
  • транзит

Если режим передвижения не указан, Google Maps отображает один или несколько наиболее подходящих режимов для указанного маршрута и/или предпочтений пользователя.

Разработчики также могут указывать идентификаторы мест с помощью параметров origin_place_id и destination_place_id . Использование идентификатора места — лучшая гарантия того, что вы укажете нужное место.

Получение идентификаторов мест с нулевой стоимостью

Для программного получения идентификаторов мест можно использовать API мест: функциональность Text Search(ID Only) . Это метод получения идентификаторов мест с нулевыми затратами. Узнайте больше о запросе Place ID и API мест (New) .

Запрос на текстовый поиск API Places (только идентификатор): 

curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'

Ответ текстового поиска API Places (только идентификатор): 

{
  "places": [
    {
      "id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
    }
  ]
}

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

Указания от текущего местоположения пользователя
Указания от текущего местоположения пользователя

Сценарий 3: Предоставление пошаговой навигации 

https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate

Установка dir_action=navigate в URL-адресе запустит Google Maps в режиме пошаговой навигации, если текущее местоположение пользователя (местоположение устройства) доступно и используется в качестве источника (явно указано или неявно используется, когда параметр источника опущен). В противном случае будет отображаться предварительный просмотр маршрута.

Пошаговая навигация запускается, когда задано dir_action=navigate и:

  • Указан источник, который находится недалеко от текущего местоположения пользователя.
  • Источник не указан, а текущее местоположение пользователя доступно.

Предварительный просмотр маршрута запускается, когда:

  • dir_action=navigate не установлен
  • dir_action=navigate установлен и указан источник, который не находится близко к текущему местоположению пользователя
  • dir_action=navigate установлен, источник опущен, а текущее местоположение пользователя недоступно

Обратите внимание, что навигация доступна не во всех продуктах Google Maps, таких как Google Maps Web, и/или между всеми пунктами назначения. В этих случаях этот параметр будет проигнорирован.

Пошаговая навигацияПредварительный просмотр маршрута
Пошаговая навигация
Предварительный просмотр маршрута

Заключение

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

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

  • Если цель — обеспечить немедленную навигацию, включите параметр dir_action=navigate для запуска пошаговой навигации. Навигация начнется с текущего местоположения пользователя, если местоположение устройства доступно и используется в качестве источника (явно задано или опущено)

Выбор правильного подхода для вашего приложения

У вас есть два основных варианта: использовать предварительно отформатированные URL-адреса, предоставляемые API Places, или вручную создавать URL-адреса Maps в вашем приложении. Каждый подход имеет свой собственный набор преимуществ и недостатков.

API мест:

  • Поля googleMapsUri и googleMapsLinks в ответе Place Details предоставляют готовые к использованию URL-адреса. Это сокращает время разработки и минимизирует риск ошибок в форматировании URL-адресов.

  • Предоставляет меньший контроль над конфигурацией направлений. Хотя googleMapsLinks предлагает базовые направления, он не поддерживает путевые точки или расширенную настройку. Кроме того, он относительно менее прост в запуске пошаговой навигации напрямую.

URL-адреса карт:

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

  • Требует более глубокого понимания параметров и структуры URL. Ручное построение увеличивает вероятность ошибок, если не сделано тщательно.

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

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

Для параметра 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=YourAppName&utm_campaign=place_details_search

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

Следующие шаги

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

Участники

Основные авторы:

Тереза ​​Цинь | Инженер по решениям платформы Google Maps