Объекты Intent для Google Карт на платформе Android

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

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

Обзор

Объекты Intent позволяют запускать операцию в другом приложении – достаточно в объекте Intent описать простое действие, которое необходимо выполнить (например, "показать карту" или "посмотреть маршруты в аэропорт"). Приложение "Google Карты" для Android поддерживает несколько разных вариантов таких объектов. Это позволяет запускать Google Карты и выполнять одно из четырех действий:

  1. Показывать карту с заданным местоположением и уровнем масштабирования.
  2. Искать местоположения и места и показывать их на карте.
  3. Запрашивать маршруты между двумя точками. Маршруты можно строить для трех видов транспорта: автомобиля, велосипеда и пешехода.
  4. Показывать панорамные изображения в Google Просмотре улиц.

На этой странице описаны намерения, которые можно использовать с приложением "Google Карты" для Android. Подробнее о намерениях и фильтрах намерений и распространенных намерениях…

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

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

  • Действие. Все намерения Google Карт вызываются как действие View (Просмотр) – ACTION_VIEW.
  • URI. В намерениях Google Карт используются закодированные в URL URI, которые указывают на выбранное действие и данные, необходимые для его выполнения.

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

После создания объекта Intent вы можете запросить запуск связанного приложения несколькими способами. Обычно для этого используется метод startActivity(), которому передается значение Intent. Система запустит нужное приложение, в данном случае Google Карты, и начнет соответствующий Activity.

Java

// 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);

Kotlin

// 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, не используйте намерение и, если возможно, отключите функцию, которая его вызывает.

Java

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

Kotlin

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

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

Java

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);
}

Kotlin

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 Карт, должны быть закодированы как URI. Например, строка 1st & Pike, Seattle должна стать строкой 1st%20%26%20Pike%2C%20Seattle. Пробелы в строке можно кодировать символами %20 или заменять знаком плюса (+).

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

Java

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

Kotlin

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 (отдельные здания). Максимальное значение может различаться в зависимости от данных карты, доступных для выбранного местоположения.

Примеры

Java

// 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);

Kotlin

// 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 Карты попытаются найти местоположение рядом с указанными вами координатами, которое соответствует вашим критериям. Если местоположение не указано, Google Карты попытаются найти предложения поблизости. Пример:

Java

// 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);

Kotlin

// 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 будет предпринята попытка найти рестораны на уровне города, а не поблизости.

Java

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);

Kotlin

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)

Если вы ищете определенный адрес, на карте появится маркер.

Java

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);

Kotlin

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

Java

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

Kotlin

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

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

Java

// 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);

Kotlin

// 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 указан как координаты широты и долготы.

Java

// 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);

Kotlin

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

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

Java

// 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.

Kotlin

// 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 Картах с пошаговыми инструкциями для указанного адреса или координат. Маршруты всегда строятся от текущего местоположения пользователя.

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

Параметры

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

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

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

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

    • t за проезд по платным дорогам
    • h для шоссе
    • f для паромов

Примеры

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

Java

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);

Kotlin

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. Маршрут до зоопарка Таронга

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

Java

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);

Kotlin

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)

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

Java

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);

Kotlin

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 возвращает маршрут в Индии.

Java

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);

Kotlin

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)

Как посмотреть панораму в Просмотре улиц

Используйте намерение google.streetview, чтобы запустить Google Просмотр улиц. Google Просмотр улиц – это сервис, предоставляющий доступ к панорамам множества разных мест по всему миру. Область покрытия сервиса постоянно расширяется. Также доступны сферы, добавленные пользователями, и специальные коллекции Просмотра улиц.

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 – это идентификатор панорамы. Если указаны и panoid, и cbll, Google Карты используют идентификатор панорамы. Идентификаторы панорам доступны в приложении Android из объекта StreetViewPanoramaLocation.

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

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

Примеры

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

Java

// 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);

Kotlin

// 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)
Пирамиды в Просмотре улиц
Рисунок 3. Пирамиды в Просмотре улиц