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

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

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

Обзор

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

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

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

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

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

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

• Пакет : Вызов функции 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-кодированные строки запроса

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

Для кодирования строк можно использовать метод encode() объекта android.net.Uri . Например:

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: для отображения карты в указанном месте и с заданным уровнем масштабирования.

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)

Вы можете дополнительно скорректировать результаты поиска, указав параметр масштабирования вместе со строкой запроса. В следующем примере добавление масштабирования в 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 , но в качестве строки запроса передается адрес. При поиске конкретного местоположения широта и долгота не требуются. Однако, если вы не знаете точный адрес, вы можете попытаться исказить результаты поиска, указав координаты. Например, поиск адреса по запросу «Главная улица» может дать слишком много результатов.

// 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=-33.8666,151.1957(Google+Sydney)");
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)

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

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 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. Значение zoom, равное 1, удваивает увеличение. Масштабирование ограничено значениями от 0 до максимального уровня масштабирования для текущей панорамы. Это означает, что любое значение, выходящее за пределы этого диапазона, устанавливается на ближайшее крайнее значение, попадающее в этот диапазон. Например, значение -1 устанавливается равным 0. Zoom — четвертое из пяти значений, разделенных запятыми.
  • tilt : определяет угол наклона камеры — вверх или вниз. Диапазон значений — от -90 до 0 и от -90 до 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)