Намерения Google Maps для Android

Приложение Google Maps для Android предоставляет несколько намерений, которые можно использовать для запуска Google Maps в режимах отображения, поиска, навигации или Street View. Чтобы встроить карту в приложение, обратитесь к Maps SDK для Android Quickstart .

Для платформ Android Automotive OS (AAOS) есть особые соображения и доступны дополнительные намерения. Подробнее см. в документации Google Maps for Android Automotive Intents .

Обзор

Намерения позволяют вам начать действие в другом приложении, описав действие, которое вы хотели бы выполнить (например, «отобразить карту» или «показать маршрут до аэропорта») в объекте Intent . Приложение Google Maps для Android поддерживает несколько различных намерений, позволяя вам запустить приложение Google Maps и выполнить одно из четырех действий:

  1. Отображение карты в указанном месте и с указанным уровнем масштабирования.
  2. Найдите нужные места или локации и отобразите их на карте.
  3. Запросить указания из одного места в другое. Указания могут быть возвращены для трех видов транспорта: на автомобиле, пешком, на велосипеде.
  4. Отображение панорамных изображений в Google Street View.

На этой странице описываются намерения, которые можно использовать с приложением Google Maps для Android. Для получения дополнительной информации о намерениях см. Намерения и фильтры намерений и Общие намерения .

Запросы намерений

Чтобы запустить Google Maps с намерением, необходимо сначала создать объект Intent , указав его действие, URI и пакет.

  • Действие : Все намерения Google Maps вызываются как действие просмотра — ACTION_VIEW .
  • URI : Намерения Google Карт используют URL-кодированные URI, которые определяют выбранное действие, а также некоторые данные, с которыми это действие выполняется.

  • Package : Вызов setPackage("com.google.android.apps.maps") гарантирует, что приложение Google Maps для Android обрабатывает Intent. Если пакет не установлен, система определяет, какие приложения могут обрабатывать Intent . Если доступно несколько приложений, пользователю может быть предложено выбрать, какое приложение он хотел бы использовать.

После создания Intent вы можете запросить, чтобы система запустила соответствующее приложение несколькими способами. Распространенный метод — передать Intent методу startActivity() . Система запускает необходимое приложение — в данном случае Google Maps — и начинает соответствующее Activity .

Ява 

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

Котлин 

// Create a Uri from an intent string. Use the result to create an Intent.
val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988")
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps")
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent)

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

Чтобы проверить, доступно ли приложение для получения намерения, вызовите resolveActivity() для вашего объекта Intent . Если результат не равен null, есть по крайней мере одно приложение, которое может обработать намерение, и можно безопасно вызвать startActivity() . Если результат равен null , не используйте намерение и, если возможно, отключите функцию, которая вызывает намерение.

Ява 

if (mapIntent.resolveActivity(getPackageManager()) != null) {
    ...
}

Котлин 

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

Например, чтобы отобразить карту Сан-Франциско, вы можете использовать следующий код:

Ява 

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(mapIntent);
}

Котлин 

val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
mapIntent.resolveActivity(packageManager)?.let {
    startActivity(mapIntent)
}

Строки запроса, закодированные в URL

Все строки, передаваемые в Google Maps Intents, должны быть закодированы в URI. Например, строка 1st & Pike, Seattle должна стать 1st%20%26%20Pike%2C%20Seattle . Пробелы в строке можно закодировать с помощью %20 или заменить знаком плюс ( + ).

Вы можете использовать метод android.net.Uri parse() для кодирования ваших строк. Например:

Ява 

Uri gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

Котлин 

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

Показать карту

Используйте geo: intent для отображения карты в указанном месте и с указанным уровнем масштабирования.

geo:latitude,longitude?z=zoom

Параметры

  • latitude и longitude задают центральную точку карты.
  • z опционально устанавливает начальный уровень масштабирования карты. Допустимые значения находятся в диапазоне от 0 (весь мир) до 21 (отдельные здания). Верхний предел может варьироваться в зависимости от данных карты, доступных в выбранном месте.

Примеры

Ява 

// Creates an Intent that loads a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

// Creates an Intent that loads a map of San Francisco
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

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

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

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

Параметры

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

  • q определяет место(а), которое нужно выделить на карте. Параметр q обязателен для всех поисковых запросов. Он принимает местоположение как название места или адрес. Строка должна быть закодирована в URL , поэтому адрес, такой как City Hall, New York, NY следует преобразовать в City+Hall,New+York,NY .

  • label позволяет вам установить пользовательскую метку в месте, указанном на карте. label должна быть указана как строка.

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

Ява 

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Search for restaurants in San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

// Search for restaurants nearby.
val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Search for restaurants in San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
Поиск Рестораны в Сан-Франциско
Рисунок 1. Поиск ресторанов в Сан-Франциско

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

Ява 

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

При поиске определенного адреса в этом месте отображается булавка.

Ява 

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

В предыдущем примере задаются широта и долгота 0 , 0 , но адрес передается в качестве строки запроса. При поиске определенного местоположения широта и долгота не требуются. Однако, если вы не знаете точный адрес, вы можете попытаться сместить результаты поиска, указав координаты. Например, выполнение поиска адреса для «Main Street» может вернуть слишком много результатов.

Ява 

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Котлин 

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

Добавление широты и долготы к URI намерения смещает результаты в сторону определенной области:

Ява 

// Searches for 'Main Street' near San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

// Searches for 'Main Street' near San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=101+main+street")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Если вы знаете, что ваш поиск возвращает одно значение, вы можете передать необязательную метку. Метки должны быть указаны как строка и отображаться под маркером карты. Обратите внимание, что метки доступны только в том случае, если q указано как координата широты и долготы.

Ява 

// Display a label at the location of Google's Sydney office.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=Google+Sydney@-33.8666,151.1957");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

// Display a label at the location of Google's Sydney office.
val gmmIntentUri =
    Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

В качестве альтернативы почтовому адресу или широте и долготе вы можете отобразить булавку в известном месте с помощью плюс-кода .

Ява 

// Display the location of Google, San Francisco using a global plus code.
Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX");
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco");
// Construct and use the Intent as in the preceding examples.

Котлин 

// Display the location of Google, San Francisco using a global plus code.
var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX")
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco")
// Construct and use the Intent as in the preceding examples.

Запустить пошаговую навигацию

Используйте этот URI намерения для запуска навигации Google Maps с пошаговыми инструкциями по указанному адресу или координатам. Указания всегда даются из текущего местоположения пользователя. 

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude

Параметры

  • q : Устанавливает конечную точку для навигационных поисков. Это значение может быть координатами широты и долготы или адресом в формате запроса. Если это строка запроса, которая возвращает более одного результата, выбирается первый результат.

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

    • d для вождения (по умолчанию)
    • b для езды на велосипеде
    • l для двухколесного транспортного средства
    • w для ходьбы

  • avoid задает объекты, которые маршрут должен избегать. avoid является необязательным и может быть установлен в одно или несколько из следующих значений:

    • t для платных дорог
    • h для автомагистралей
    • f для паромов

Примеры

Следующее Intent запрашивает пошаговую навигацию до зоопарка Таронга в Сиднее, Австралия:

Ява 

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
Как добраться до зоопарка Таронга
Рисунок 2. Как добраться до зоопарка Таронга

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

Ява 

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Если вы предпочитаете немного подвигаться, вы можете запросить маршрут для езды на велосипеде.

Ява 

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Если вы предпочитаете использовать моторизованный двухколесный транспорт, вы можете запросить, чтобы указания включали узкие дороги и тропы, недоступные для автомобилей. Следующее intent возвращает маршрут в Индии.

Ява 

Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

val gmmIntentUri =
    Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Отобразить панораму Street View

Используйте намерение google.streetview для запуска Google Street View. Google Street View обеспечивает панорамные виды из определенных мест по всей своей зоне покрытия . Также доступны предоставленные пользователями фотосферы и специальные коллекции Street View . 

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

Параметры

Все URI google.streetview должны включать параметр cbll или panoid :

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

  • panoid — это определенный идентификатор панорамы. Google Maps использует идентификатор панорамы, если указаны и panoid , и cbll . Идентификаторы панорам доступны для приложения Android из объекта StreetViewPanoramaLocation .

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

    • bearing : указывает направление камеры по компасу в градусах по часовой стрелке от севера. Истинный север — 0, восток — 90, юг — 180, запад —
      1. Значения, переданные в обертки подшипников; то есть 0°, 360° и 720°, все указывают в одном направлении. Пеленг определяется как второе из пяти значений, разделенных запятыми.
    • zoom : Устанавливает уровень масштабирования камеры. Уровень масштабирования по умолчанию установлен на 0. Масштабирование на 1 удвоит увеличение. Масштабирование ограничивается значением от 0 до максимального уровня масштабирования для текущей панорамы. Это означает, что любое значение, выходящее за пределы этого диапазона, устанавливается на ближайшее предельное значение, попадающее в диапазон. Например, значение -1 устанавливается на 0. Масштабирование является четвертым из пяти значений, разделенных запятыми.
    • tilt : определяет угол наклона камеры вверх или вниз. Диапазон составляет от -90 до 0 до 90, где 90 направлено прямо вниз, 0 по центру горизонта и -90 направлено прямо вверх.

Примеры

Ниже приведены некоторые примеры использования намерения Street View.

Ява 

// Displays an image of the Swiss Alps.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Котлин 

// Displays an image of the Swiss Alps.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=46.414382,10.013988")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
val gmmIntentUri =
    Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
Пирамиды в Street View
Рисунок 3. Пирамиды в Street View