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 vista da rua. Se você quiser incorporar um mapa no seu app, consulte o guia de introdução da API Google Maps Android.

Observação: os URLs do Maps permitem criar um URL universal em várias plataformas para abrir o Google Maps e fazer pesquisas, receber direções, mostrar visualizações de mapa e exibir imagens panorâmicas. Recomendamos o uso dos URLs do Maps em várias plataformas para abrir o Google Maps, já que esses URLs universais permitem um processamento mais amplo das solicitações de mapas, independentemente da plataforma do usuário. Use as intents do Maps específicas do Android apenas para recursos que só podem funcionar em uma plataforma móvel (por exemplo, navegação passo a passo).

Visão geral

As intents permitem iniciar uma atividade em outro app descrevendo uma ação simples que você gostaria de realizar (como "exibir um mapa" ou "mostrar rotas para o aeroporto") em um objeto Intent. O app Google Maps para Android oferece suporte a várias intents, permitindo que você o inicie e realize uma destas quatro ações:

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 modos de transporte: condução, caminhada e bicicleta.
4. Exibir imagens de panorama no Google Street View.

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

Solicitações de intent

Para iniciar o Google Maps com uma intent, é preciso antes criar um objeto Intent e especificar a ação, a URI e o pacote.

• Ação: todas as intenções do Google Maps são chamadas como uma ação Visualizar: ACTION_VIEW.
• URI: as intenções do Google Maps usam URL codificado que especificam uma ação desejada, juntamente com alguns dados para a execução da 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á ser consultado sobre qual app ele quer 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 método startActivity(). O sistema vai 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 consegue identificar um app que possa responder à intent, o app pode falhar. Por isso, verifique antes se um aplicativo recebedor está instalado antes de apresentar uma dessas intenções ao 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 "1st & Pike, Seattle" precisa ser 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 parse() android.net.Uri 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 mostrar um mapa em uma localização e com o nível de zoom especificados.

geo:latitude,longitude?z=zoom

Parâmetros

• latitude e longitude definem o ponto central do mapa.
• z opcionalmente define o nível de zoom inicial do mapa. Os valores aceitos variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados de mapa disponíveis na localização selecionada.

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 tem um único resultado, você pode usar essa intent para mostrar um pino em um local ou endereço específico, como um marco, 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 aceita 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 uma localização como um nome de lugar ou endereço. A string precisa ser codificada em URL. Portanto, um endereço como "Prefeitura, Nova York, NY" precisa ser convertido em Prefeitura,Nova+York,NY.

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

Pesquisa de categoria

Se você passar um termo de pesquisa genérico, o Google Maps tentará encontrar uma localização perto da latitude/longitude especificada e que corresponde aos seus critérios. Se nenhum local for especificado, o Google Maps vai tentar encontrar listas 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)

Você pode direcionar os resultados da pesquisa ainda mais especificando um parâmetro de zoom junto com a string de consulta. No exemplo abaixo, a adição de um zoom de 10 vai tentar encontrar restaurantes na cidade em vez de em locais próximos.

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)

Pesquisa de locais

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, mas transmite um endereço como uma string de consulta. Na pesquisa de uma localização muito específica, a latitude e a longitude não são necessárias. No entanto, se você não souber o endereço exato, pode tentar direcionar os resultados da pesquisa especificando uma coordenada. Por exemplo, a execução de uma pesquisa de endereço de "Main Street" retorna 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")

A adição de latitude/longitude à URI da intent direciona os resultados para uma determinada área:

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 vai retornar um único valor, pode transmitir um rótulo opcional. É necessário definir os rótulos como string. Eles vão aparecer 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, é possível 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 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

Como iniciar a navegação guiada

Use essa intent para iniciar a navegação do Google Maps com rotas curva a curva até o endereço ou a coordenada especificado. As rotas são sempre fornecidas a partir do local atual do usuário.

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

Parâmetros

• q: define o ponto de chegada para as pesquisas de navegação. Esse valor pode ser latitude, coordenadas de 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. O modo é opcional e pode ser definido como um dos seguintes:

  • d para dirigir (padrão)
  • b para andar de bicicleta
  • l para motocicletas
  • w para caminhar

• avoid define os recursos que a rota deve tentar evitar. Evitar é opcional e pode ser definido para um ou mais de:

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

Exemplos

O Intent abaixo solicita navegação curva a curva até o Taronga Zoo, em Sidnei, 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)

Se preferir não pagar pedágios ou pegar balsas, é possível solicitar uma rota que tente evitar estas coisas.

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ê prefere um pouco de exercício, pode solicitar rotas para 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 um veículo motorizado de duas rodas, peça para que as direções incluam estradas 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)

Como 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 área de cobertura. Photospheres contribuídas por 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 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 passe para 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. Os IDs de panorama estão disponíveis para um app Android no objeto StreetViewPanoramaLocation.

• cbp é um parâmetro opcional que ajusta a orientação inicial da câmera. O parâmetro cbp aceita cinco valores separados por vírgula, todos opcionais. Os valores mais importantes são o segundo, o quarto e o quinto, que definem respectivamente rumo, zoom e inclinação. O primeiro e o terceiro valores não são aceitos 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 para o rumo são cíclicos, ou seja, 0°, 360° e 720° apontam para a mesma direção. O rumo é definido como o segundo dos 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 dobra a ampliação. O zoom é limitado entre 0 e o nível de zoom máximo do panorama atual. Isso significa que qualquer valor fora desse intervalo é definido como o extremo mais próximo dentro do intervalo. Por exemplo, um valor de -1 será definido como 0. O zoom é o quarto dos cinco valores separados por vírgula.
  • tilt: especifica o ângulo vertical da câmera. O intervalo varia de -90 a 0 e de 0 a 90, onde 90 aponta para baixo, 0 é centralizado no horizonte e -90 aponta 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)