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

Приложение Google Maps для Android предоставляет несколько возможностей, которые можно использовать для запуска Google Maps в режимах отображения, поиска, навигации или просмотра улиц. Если вы хотите встроить карту в свое приложение, обратитесь к Руководству по началу работы с API Google Maps для Android.

Обзор

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

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

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

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

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

• Действие : Все намерения Google Maps вызываются действием «Просмотр» — ACTION_VIEW .
• URI : намерения Google Maps используют закодированный URL-адрес , который определяет желаемое действие, а также некоторые данные для выполнения действия.
• Пакет : вызов setPackage("com.google.android.apps.maps") гарантирует, что приложение Google Maps для Android обработает намерение. Если пакет не установлен, система определит, какие приложения могут обрабатывать 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, должны иметь кодировку 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 will load 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 will load 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 попытаются найти местоположение рядом с указанной вами широтой и долготой, соответствующее вашим критериям. Если местоположение не указано, Карты Google попытаются найти ближайшие объекты. Например:

// 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' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

// Searching for 'Main Street' will return 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 examples above

// 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 examples above

Запускаем пошаговую навигацию

Используйте это намерение, чтобы запустить навигацию по Картам Google с пошаговыми инструкциями по указанному адресу или координатам. Маршруты всегда указываются от текущего местоположения пользователя.

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

Параметры

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

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

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

• 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 ). Приложение отобразит панораму, сфотографированную ближе всего к этому месту. Поскольку изображения Просмотра улиц периодически обновляются и каждый раз фотографии могут быть сделаны с несколько разных позиций, возможно, что ваше местоположение может быть привязано к другой панораме при обновлении изображений.

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

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

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

Примеры

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

// 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 will angle 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 will angle 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)