Intents do Google Maps para Android

O app Google Maps para Android expõe várias intents que podem ser usadas para iniciar o Google Maps nos modos de exibição, pesquisa, navegação ou Street View. Se você quiser incorporar um mapa ao seu app, consulte o Guia para iniciantes da API Google Maps Android.

Visão geral

As intents permitem que você inicie uma atividade em outro app descrevendo uma ação simples que você quer realizar, como "exibir um mapa" ou "mostrar rotas ao aeroporto") em um objeto Intent. O app Google Maps para Android é compatível com várias intents, permitindo que você inicie o app Google Maps e execute uma das quatro ações a seguir:

  1. Exibir um mapa em um local e nível de zoom especificados.
  2. Procurar locais ou lugares e exibi-los em um mapa.
  3. Solicitar rotas de um local para outro. As rotas podem ser retornadas para três meios de transporte: carro, caminhada e bicicleta.
  4. Exibir imagens do panorama no Google Street View.

Esta página descreve as intents que podem ser usadas com o app Google Maps para Android. Para ver mais informações sobre Intents e filtros de intents ou Intents comuns à Plataforma Android, consulte a documentação do desenvolvedor Android.

Solicitações de intent

Para iniciar o Google Maps com uma intent, primeiro crie um objeto Intent, especificando a ação, o URI e o pacote dele.

  • Ação: todas as intents do Google Maps são chamadas como uma ação de visualização: ACTION_VIEW.
  • URI: as intents do Google Maps usam URL codificado que especifica uma ação desejada, além de alguns dados para executar a ação.
  • Pacote: chamar setPackage("com.google.android.apps.maps") garante que o app Google Maps para Android processe a intent. Se o pacote não for definido, o sistema determinará quais apps podem processar a Intent. Se vários apps estiverem disponíveis, talvez o usuário precise escolher qual app quer usar.

Depois de criar o Intent, você pode solicitar que o sistema inicie o app relacionado de várias maneiras. Um método comum é transmitir o Intent para o método startActivity(). O sistema iniciará o app necessário, neste caso, o Google Maps, e iniciará o Activity correspondente.

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)

Se o sistema não puder identificar um app que possa responder à intent, seu app poderá falhar. Por esse motivo, verifique primeiro se um aplicativo receptor está instalado antes de apresentar uma dessas intents a um usuário.

Para verificar se um app está disponível para receber a intent, chame resolveActivity() no objeto Intent. Se o resultado não for nulo, há pelo menos um app que pode processar a intent e é seguro chamar startActivity(). Se o resultado for null, não use a intent e, se possível, desative o recurso que a invoca.

Java

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

Kotlin

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

Por exemplo, para exibir um mapa de São Francisco, você pode usar este código:

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

Strings de consulta codificadas em URL

É necessário codificar para URI todas as strings passadas para as intenções do Google Maps. Por exemplo, a string "quot;1st & Pike, Seattle" deve se tornar 1st%20%26%20Pike%2C%20Seattle. Os espaços na string podem ser codificados com %20 ou substituídos pelo sinal de mais (+).

Você pode usar o método android.net.Uri parse() para codificar as strings. Exemplo:

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

Exibir um mapa

Use a intent geo: para exibir um mapa em uma localização e um nível de zoom especificados.

geo:latitude,longitude?z=zoom

Parâmetros

  • latitude e longitude definem o ponto central do mapa.
  • Opcionalmente, z define o nível de zoom inicial do mapa. Os valores aceitos variam de 0 (todo o mundo) a 21 (edifícios individuais). O limite superior varia de acordo com os dados do mapa disponíveis no local selecionado.

Exemplos

Java

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

Kotlin

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

Pesquisar um local

Use essa intenção para exibir consultas de pesquisa em uma porta de visualização especificada. Quando a consulta tiver um único resultado, será possível usar a intent para exibir um alfinete em um lugar ou endereço específico, como um ponto de referência, empresa, elemento geográfico ou cidade.

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

Parâmetros

Além dos parâmetros usados para exibir um mapa, a Pesquisa é compatível com os seguintes parâmetros:

  • q define os lugares a serem destacados no mapa. O parâmetro q é obrigatório para todas as solicitações de pesquisa. Ele aceita um local como nome ou endereço do lugar. A string precisa ser codificada por URL. Portanto, um endereço como "City Hall, New York, NY" deve ser convertido em City+Hall,New+York,NY.

  • label permite que você defina um marcador personalizado em um local identificado no mapa. O label precisa ser especificado como uma string.

Se você transmitir um termo de pesquisa geral, o Google Maps tentará encontrar um local próximo à latitude/longitude especificada que corresponda aos seus critérios. Se nenhum local for especificado, o Google Maps tentará encontrar as listagens próximas. Exemplo:

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)

Procurando restaurantes em São Francisco

Você pode influenciar ainda mais os resultados da pesquisa especificando um parâmetro de zoom com a string de consulta. No exemplo abaixo, adicionar um zoom de 10 tentará encontrar restaurantes no nível da cidade em vez de nas proximidades.

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)

A pesquisa de um endereço específico exibe um pino nessa localização.

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)

O exemplo acima define uma latitude/longitude de 0,0 e passa um endereço como string de consulta. Para pesquisar um local muito específico, a latitude e a longitude não são necessárias. No entanto, se você não souber o endereço exato, especifique os resultados da pesquisa especificando uma coordenada. Por exemplo, executar uma pesquisa de endereço por "#39;Main Street'" retornará muitos resultados.

Java

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

Kotlin

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

Adicionar uma latitude/longitude ao URI de intent direciona os resultados para uma área específica:

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)

Quando você sabe que sua pesquisa retornará um único valor, pode querer transmitir um rótulo opcional. Os rótulos precisam ser especificados como uma string e aparecerão abaixo do marcador do mapa. Os rótulos só estão disponíveis quando q é especificado como uma coordenada de latitude/longitude.

Java

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

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)

Como alternativa a um endereço ou uma latitude/longitude, você pode exibir um alfinete em um local conhecido usando um código de adição.

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

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

Iniciar a navegação passo a passo

Use essa intent para iniciar a navegação do Google Maps com rotas passo a passo para o endereço ou a coordenada especificada. As rotas são sempre fornecidas com base no local atual do usuário.

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

Parâmetros

  • q: define o ponto final para as pesquisas de navegação. Esse valor pode ser latitude, coordenadas de longitude ou um endereço formatado por consulta. Se for uma string de consulta que retorna mais de um resultado, o primeiro resultado será selecionado.

  • mode define o método de transporte. O modo é opcional e pode ser definido como um destes:

    • d de carro (padrão)
    • b de bicicleta
    • l para motocicletas
    • w para caminhada
  • avoid define os recursos que a rota tentará evitar. Evitar é opcional e pode ser definido como um ou mais de:

    • t para pedágios
    • h para rodovias
    • f para balsas

Exemplos

O Intent abaixo solicitará a navegação guiada para o Zoológico de Taronga, em Sydney, na Austrália:

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)

Rotas para o Zoológico de Taronga

Se você não quer pagar pedágios ou pegar uma balsa, pode solicitar o encaminhamento para evitar que isso aconteça.

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)

Se preferir um pouco de exercício, você pode solicitar rotas de bicicleta.

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)

Se preferir pegar um motociclista motorizado, você pode solicitar que as rotas incluam vias estreitas e trilhas indisponíveis para carros. O intent abaixo retorna uma rota na Índia.

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)

Exibir um panorama do Street View

Use a intent google.streetview para iniciar o Google Street View. O Google Street View oferece vistas panorâmicas de locais designados em toda a área de cobertura. Photo Spheres com contribuições de usuários e coleções especiais do Street View também estão disponíveis.

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

Parâmetros

Todos os URIs do google.streetview precisam incluir um parâmetro cbll ou panoid.

  • cbll aceita uma latitude e uma longitude como valores separados por vírgula (46.414382,10.013988). O app exibirá o panorama fotografado mais próximo desse local. Como as imagens do Street View são atualizadas periodicamente, e as fotos podem ser tiradas em posições ligeiramente diferentes a cada vez, é possível que sua localização seja alinhada a um panorama diferente quando as imagens forem atualizadas.

  • panoid é um ID de panorama específico. O Google Maps usará o ID do panorama se um panoid e um cbll forem especificados. Esses IDs estão disponíveis para um app Android pelo objeto StreetViewPanoramaLocation.

  • cbp é um parâmetro opcional que ajusta a orientação inicial da câmera. O parâmetro cbp usa cinco valores separados por vírgulas, todos opcionais. Os valores mais significativos são o segundo, o quarto e o quinto, que definem o rolamento, o zoom e a inclinação, respectivamente. O primeiro e o terceiro valores não são compatíveis e precisam ser definidos como 0.

    • bearing: indica a direção da bússola da câmera em graus no sentido horário a partir do Norte. O norte verdadeiro é 0, o leste é 90, o sul é 180 e o oeste é 270. Os valores transmitidos serão encapsulados, ou seja, 0°, 360° e 720°, todos na mesma direção. Rolamento é definido como o segundo de cinco valores separados por vírgulas.
    • zoom: define o nível de zoom da câmera. O nível de zoom padrão é definido como 0. Um zoom de 1 dobra a ampliação. O zoom é fixado entre 0 e o nível máximo do zoom do panorama atual. Isso significa que qualquer valor fora desse intervalo será definido como o extremo mais próximo que estiver dentro do intervalo. Por exemplo, o valor -1 será definido como 0. O zoom é o quarto dos cinco valores separados por vírgulas.
    • tilt: especifica o ângulo para cima ou para baixo da câmera. O intervalo é de -90 a 0 até 90, sendo 90 olhando para baixo, 0 centralizado no horizonte e -90 olhando para cima.

Exemplos

Veja a seguir alguns exemplos do uso da intenção Street View.

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

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

Pirâmides no Street View