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. Para incorporar um mapa ao seu app, consulte o Guia de início rápido do SDK do Maps para Android.

Para plataformas do Android Automotive OS (AAOS), há considerações específicas e intents adicionais disponíveis. Consulte a documentação das intents do Google Maps para Android Automotive para mais detalhes.

Visão geral

As intents permitem iniciar uma atividade em outro app descrevendo uma ação que você gostaria de realizar (por exemplo, "mostrar um mapa" ou "mostrar rotas para o aeroporto") em um Intent objeto. O app Google Maps para Android é compatível com várias intents,permitindo que você o inicie e realize uma das quatro ações a seguir:

  1. Mostrar um mapa em um local e nível de zoom especificados.
  2. Pesquisar locais ou lugares e mostrá-los em um mapa.
  3. Solicitar rotas de um local para outro. As rotas podem ser retornadas para três modos de transporte: carro, a pé e bicicleta.
  4. Mostrar imagens panorâmicas no Google Street View.

Esta página descreve as intents que podem ser usadas com o app Google Maps para Android. Para mais informações sobre intents, consulte Intents e filtros de intent e Intents comuns.

Solicitações de intent

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

  • 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 URIs codificados por URL que especificam uma ação selecionada, além de alguns dados para realizar 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 estiver definido, o sistema vai determinar quais apps podem processar a Intent. Se vários apps estiverem disponíveis, o usuário poderá escolher qual usar.

Depois de criar a Intent, você pode solicitar que o sistema inicie o app relacionado de várias maneiras. Um método comum é transmitir o Intent para o startActivity() método. O sistema inicia o app necessário — neste caso, o Google Maps — e inicia a 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 conseguir identificar um app que possa responder à intent, seu app poderá falhar. Por esse motivo, primeiro verifique 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 mostrar um mapa de São Francisco, use o código a seguir:

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 por URL

Todas as strings transmitidas às intents do Google Maps precisam ser codificadas por URI. Por exemplo, a string 1st & Pike, Seattle precisa se tornar 1st%20%26%20Pike%2C%20Seattle. Os espaços na string podem ser codificados com %20 ou substituídos pelo sinal de adição (+).

Você pode usar o método android.net.Uri encode() para codificar suas strings. Por 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"))

Mostrar um mapa

Use a intent geo: para mostrar um mapa em um local e nível de zoom especificados.

geo:latitude,longitude?z=zoom

Parâmetros

  • latitude e longitude definem o ponto central do mapa.
  • z define opcionalmente o nível de zoom inicial do mapa. Os valores aceitos variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite superior pode variar dependendo dos dados do mapa disponíveis no local selecionado.

Exemplos

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)

Pesquisar um local

Use essa intent para mostrar consultas de pesquisa em uma janela de visualização especificada. Quando a consulta tem um único resultado, você pode usar essa intent para mostrar um alfinete em um lugar ou endereço específico, como um ponto de referência, uma empresa, uma característica geográfica ou uma 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 mostrar um mapa, a pesquisa oferece suporte aos 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 um nome de lugar ou endereço. A string precisa ser codificada por URL. Portanto, um endereço como City Hall, New York, NY precisa ser convertido em City+Hall,New+York,NY.

  • label permite definir um rótulo personalizado em um lugar identificado no mapa. O label precisa ser especificado como uma string.

Se você transmitir um termo de pesquisa geral, o Google Maps vai tentar encontrar um local perto da latitude e longitude especificadas que corresponda aos seus critérios. Se nenhum local for especificado, o Google Maps vai tentar encontrar listagens próximas. Por 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)
Pesquisando por Restaurantes em São Francisco
Figura 1. Pesquisando restaurantes em São Francisco

Você pode influenciar ainda mais os resultados da pesquisa especificando um parâmetro de zoom junto com a string de consulta. No exemplo a seguir, a adição de um zoom de 10 tenta encontrar restaurantes em nível de cidade em vez de perto.

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 mostra um alfinete nesse local.

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 anterior define uma latitude e longitude de 0,0, mas transmite um endereço como uma string de consulta. Ao pesquisar um local específico, a latitude e a longitude não são obrigatórias. No entanto, se você não souber o endereço exato, poderá tentar influenciar os resultados da pesquisa especificando uma coordenada. Por exemplo, fazer uma pesquisa de endereço para "Main Street" pode retornar muitos resultados.

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

Adicionar uma latitude e longitude ao URI da intent influencia 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 a pesquisa retorna um único valor, talvez seja necessário transmitir um rótulo opcional. Os rótulos precisam ser especificados como uma string e aparecer abaixo do marcador do mapa. Os rótulos só estão disponíveis quando q é especificado como uma coordenada de latitude e longitude.

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)

Como alternativa a um endereço ou uma latitude e longitude, você pode mostrar um alfinete em um local conhecido usando um 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.

Iniciar a navegação guiada

Use esse URI de intent para iniciar a Navegação do Google Maps com navegação guiada para o endereço ou coordenada especificados. As rotas são sempre fornecidas da localização atual do usuário.

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

Parâmetros

  • q: define o endpoint para pesquisas de navegação. Esse valor pode ser coordenadas de latitude e longitude ou um endereço formatado para 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. mode é opcional e pode ser definido como um dos seguintes:

    • d para dirigir (padrão)
    • b para bicicleta
    • l para motocicleta
    • w para caminhada

  • avoid define os recursos que a rota deve tentar evitar. avoid é opcional e pode ser definido como um ou mais dos seguintes:

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

Exemplos

As seguintes solicitações de Intent ativam a navegação guiada para o zoológico de Taronga, em Sydney, 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
Figura 2. Rotas para o zoológico de Taronga

Se você preferir não pagar pedágios ou andar de balsa, poderá solicitar rotas que tentem evitar esses recursos.

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 você preferir um pouco de exercício, poderá 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 você preferir usar uma motocicleta, poderá solicitar que as rotas incluam estradas e trilhas estreitas indisponíveis para carros. A intent a seguir 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)

Mostrar 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 sua área de cobertura. As fotos esféricas enviadas pelos usuários, e as 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 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 mostra o panorama fotografado mais próximo desse local. Como as imagens do Street View são atualizadas periodicamente e as fotografias podem ser tiradas de posições ligeiramente diferentes a cada vez, é possível que sua localização se alinhe a um panorama diferente quando as imagens forem atualizadas.

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

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

    • bearing: indica a direção 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 é
      1. Os valores transmitidos para a direção são encapsulados. Ou seja, 0°, 360° e 720° apontam na mesma direção. A direção é definida como o segundo de cinco valores separados por vírgula.
    • zoom: define o nível de zoom da câmera. O nível de zoom padrão é definido como 0. Um zoom de 1 dobraria a ampliação. O zoom é limitado entre 0 e o nível máximo de zoom para o panorama atual. Isso significa que qualquer valor fora desse intervalo é definido como o extremo mais próximo que está dentro do intervalo. Por exemplo, um valor de -1 é definido como 0. O zoom é o quarto de cinco valores separados por vírgula.
    • 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 apontando para cima.

Exemplos

Confira alguns exemplos de como usar a intent do 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 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)
Pirâmides no Street View
Figura 3. Pirâmides no Street View