Google Maps para intents do Android Automotive

Com intents do Android, é possível iniciar a navegação no Google Maps para Android Automotive.

Visão geral

Esta página descreve as intents que podem ser usadas com o Google Maps para Android Automotive. Para consultar a documentação detalhada para desenvolvedores Android, acesse:

• Intents e filtros de intent
• Intents comuns à plataforma Android

Solicitações de intent

Para iniciar o Google Maps para Android Automotive 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 strings codificadas em URI que especificam uma ação escolhida, além de alguns dados para realizar a ação.

• Pacote. A chamada de 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, talvez seja necessário escolher qual deles você quer usar.

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

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// 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 isso, primeiro verifique se um aplicativo de recebimento 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, haverá pelo menos um app que pode processar a intent, e será seguro chamar startActivity(). Se o resultado for nulo, não use a intent e, se possível, desative o recurso que a invoca.

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

Por exemplo, para iniciar a navegação ponto a ponto até o zoológico de Taronga em Sydney, use o seguinte código:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

Strings de consulta codificadas por URI

Todas as strings transmitidas às intents do Google Maps precisam ser codificadas por URI. Por exemplo, a string "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 adição (+).

Você pode usar o método android.net.Uri encode() para codificar suas strings. Por exemplo:

Uri mapIntentUri = Uri.parse("google.navigation: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. Exemplo:

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 todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.

Exemplo

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

Pesquisar um local

Use esta intent para mostrar consultas de pesquisa em uma janela de visualização especificada:

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

Parâmetros

Além dos parâmetros usados para mostrar um mapa, a Pesquisa aceita este parâmetro:

• 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 um endereço. A string precisa ter caracteres de escape de URL. Portanto, um endereço como "City Hall, New York, NY" precisa ser convertido em City+Hall%2CNew+York%2CNY.

Polarizar os resultados da pesquisa com coordenadas

Ao pesquisar um local muito específico, a latitude e a longitude não são estritamente necessárias se incluídas no parâmetro q. No entanto, se você não souber o endereço exato ou a consulta for ambígua, tente influenciar os resultados da pesquisa especificando uma coordenada. Por exemplo, uma pesquisa de endereço por "Rua Principal" pode retornar muitos resultados:

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Adicionar uma latitude e uma longitude ao URI da intent enviesa os resultados para uma área específica:

// Searches for "101 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);

Pesquisar no trajeto

Se um intent de pesquisa geo:latitude,longitude?q=query for enviado durante a navegação, ele vai acionar uma pesquisa ao longo do trajeto, e a latitude e a longitude serão ignoradas.

Pesquisar categorias predefinidas

Para oferecer suporte à integração com o veículo, o Google Maps no carro usa uma intent que mostra estas categorias predefinidas:

A intent de categoria está no formato geo:lat,lng?c=category.

Use c=<pre-defined category> independente das configurações de localidade do usuário. O Google Maps mostra resultados relevantes no local apropriado para essa categoria. Exemplo:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Outra pesquisa categórica

Se você transmitir um termo de pesquisa geral (como "restaurantes" ou "cafés") na localidade do usuário, o Google Maps para Android Automotive vai pesquisar fichas de empresas que correspondam aos critérios. Se uma latitude e longitude específicas forem fornecidas na intent geo:, a pesquisa será centralizada nesse local. Se nenhum local for especificado (por exemplo, geo:0,0), o Google Maps tenta encontrar fichas de empresas próximas. Exemplo:

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

É possível influenciar ainda mais os resultados da pesquisa especificando um parâmetro de zoom junto com a string de consulta. No exemplo a seguir, adicionar um zoom de 10 tenta encontrar restaurantes em uma cidade em vez de nas proximidades:

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

Iniciar a navegação guiada

Para conferir a documentação sobre como iniciar a navegação guiada em outros dispositivos Android, consulte Iniciar a navegação guiada em intents do Google Maps para Android.

Use essa intent para iniciar a navegação do Google Maps com rotas guiadas até um ou vários endereços ou coordenadas especificados. As rotas são sempre fornecidas a partir da localização atual do usuário.

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

Parâmetros

Para iniciar a navegação, use place ou q com waypoints, que é opcional. Para marcar um ponto de parada como uma estação de recarga, consulte Enviar um plano de viagem de veículo elétrico para o Google Maps.

• q define o endpoint para pesquisas de navegação. Pode ser uma latitude e longitude ou um endereço formatado para consulta. Se for uma string de consulta que retorna mais de um resultado, o primeiro será selecionado.

• place define o ponto final como casa ou trabalho. Especifique "casa" para iniciar o trajeto até a casa do usuário e "trabalho" para iniciar o trajeto até o local de trabalho.

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

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

• waypoints especifica um ou mais lugares intermediários para traçar rotas até o destino final especificado por q. É possível especificar vários pontos de referência usando o caractere de barra vertical (|) para separar lugares. Por exemplo, Berlin,Germany|Paris,France. Você pode usar quantos pontos de referência forem necessários. Os pontos de referência serão adicionados ao trajeto na mesma ordem em que estão listados no URL. Cada ponto de parada pode ser um endereço ou coordenadas de latitude e longitude separadas por vírgula. Além disso, é possível ter endereços e coordenadas de latitude e longitude na mesma intent. As strings precisam ser com escape de URL. Portanto, pontos de referência como "Berlin,Germany|Paris,France" precisam ser convertidos para Berlin%2CGermany%7CParis%2CFrance.

Exemplos

Essa intent vai solicitar navegação ponto a ponto até o Zoológico de Taronga, em Sydney, Austrália:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Se você preferir não pagar pedágios ou andar de balsa, peça um trajeto que tente evitar essas situações:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Se preferir navegar até sua casa, use:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Para iniciar a navegação ponto a ponto até os três endereços a seguir em ordem, transmita o Zoológico de Taronga como o destino final q e o Google Sydney e a Sydney Opera House como os pontos de referência:

1. Google Sydney

2. Ópera de Sydney

3. Zoológico de Taronga, Sydney, Austrália

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Semelhante a q, é possível representar qualquer um dos pontos de referência por uma latitude e longitude separadas por vírgula em vez de um endereço. Por exemplo, para iniciar a mesma navegação transmitindo latitude e longitude da Sydney Opera House em vez do endereço:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Enviar um plano de viagem de veículo elétrico para o Google Maps

Use essa intent de navegação com vários destinos para especificar alguns destinos como paradas para recarga de veículos elétricos (VEs). Essa intent, que estende a intent de vários pontos de parada, ajuda os motoristas a manter uma carga de bateria suficiente para chegar aos destinos sincronizando informações de paradas para recarga entre apps de planejamento de viagens de VE e o Google Maps.

Para postos de recarga, objetivos de viagem:

• Precisa conter um nome e latitude/longitude
• Pode conter opcionalmente uma saída de energia, que será usada para calcular o tempo de carregamento.

O Google usa o nome e a latitude/longitude da estação de recarga para encontrar um lugar correspondente e mostrar dados avançados, como tipos de conector, totais, velocidades e disponibilidade em tempo real, formas de pagamento aceitas e pontos de interesse (POI) do host. Por exemplo, rotas de carro em estacionamentos ao ar livre para a parte final da navegação, horários de funcionamento e avaliações. Para garantir que os postos de recarga correspondam bem aos dados do Google, use um <brand name> específico, por exemplo, ChargePoint.

Parâmetros

Os parâmetros a seguir permitem especificar detalhes do destino final e de todos os pontos de referência, incluindo aqueles designados como estações de recarga de VE.

Destino final

Para definir um posto de abastecimento como destino final, use:

• q: precisa conter o valor de latitude e longitude da estação de recarga.
• q_type: 1 especifica que o destino final é uma estação de recarga.
• q_name: o nome do destino final. Obrigatório se q_type for 1.
• q_power_output_kw: um número duplo para a potência de saída da estação de recarga em quilowatts. Opcional.

Pontos de referência

Para pontos de referência, todos os parâmetros são matrizes paralelas separadas por barras verticais (|) de valores na mesma ordem dos pontos de referência, sem incluir o destino final. Uma incompatibilidade no número de elementos em matrizes paralelas é tratada como uma intenção malformada.

Para adicionar um ou mais pontos de parada de estações de recarga, use os seguintes parâmetros, que são opcionais. Se um dos destinos for marcado como um posto de recarga, o nome do ponto de referência será obrigatório para esse destino.

• waypoints: lista de pontos de referência, conforme descrito na intent de navegação guiada. Precisa ser um valor de latitude e longitude para pontos de referência de estações de recarga.

• waypoint_types: tipos por ponto de referência especificados como um número. 0 é qualquer parada (valor padrão) e 1 é a estação de recarga.

• waypoint_names: nomes de pontos de referência. Este campo é obrigatório para estações de recarga.

• waypoint_power_outputs_kw: números de ponto flutuante para a potência da estação de recarga em quilowatts. Para estações de recarga, é possível especificar um valor de saída de energia de ponto de referência, que é usado como substituto se a estação correspondente não for encontrada. Um slot vazio significa que nenhum valor foi fornecido.

Comportamento da experiência do usuário (UX)

Para objetivos de viagem com vários destinos, a tela de visão geral da rota é mostrada, mas a navegação não é iniciada automaticamente.

Para uma intent formatada corretamente, o Google Maps vai apresentar uma tela de visão geral do trajeto para a viagem. A tela de visão geral do trajeto vai mostrar todos os pontos de parada e o destino final da intent, com recomendações de recarga quando aplicável.

Para qualquer ponto de parada ou destino final marcado como uma estação de recarga, o Google Maps vai procurar um lugar correspondente no banco de dados do Google. Para garantir que as melhores informações possíveis sejam mostradas para as estações de recarga:

• Se uma correspondência for encontrada, o Google Maps usará os dados do Google para mostrar o eletroposto na interface do usuário (UI) e fornecer uma recomendação de recarga para ele.

• Se a correspondência não for encontrada, os dados fornecidos na intent para um eletroposto (latitude-longitude, nome e potência) serão usados para mostrar o eletroposto na interface e fornecer uma recomendação de recarga.

Exemplos

Os exemplos a seguir ilustram como criar intents para vários cenários de planejamento de viagens com veículos elétricos, incluindo navegação por várias estações de recarga e processamento de potências desconhecidas.

Navegar até um destino final passando por várias estações de recarga

O intent a seguir navega até o destino final, Port Macquarie NSW, passando por duas estações de recarga, ChargePoint e Evie.

Destinos em ordem:

1. Estação de recarga da ChargePoint (localização: -32.9599188,151.6240806, potência: 6,6 kW)

2. Eletroposto Evie (localização: -31.9432539,152.4699808, potência: 350 kW)

3. Port Macquarie, NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Potência desconhecida

Se o valor de saída de energia for desconhecido, deixe o slot relevante de waypoint_power_outputs_kw vazio. Ou, se todos os slots estiverem vazios, não será necessário especificar o parâmetro waypoint_power_outputs_kw.

Destinos em ordem:

1. Estação de recarga da ChargePoint (localização: -32.9599188,151.6240806, potência: desconhecida)

2. Port Macquarie, NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Marcar o destino final como uma estação de recarga

Para marcar o destino final como uma estação de recarga, especifique os parâmetros q_type, q_name e q_power_output_kw.

Destinos em ordem:

1. Zoológico de Taronga, Sydney, Austrália

2. Estação de recarga da ChargePoint (localização: -32.9599188,151.6240806, potência: desconhecida)

3. Eletroposto Evie (localização: -31.9432539,152.4699808, potência: 350 kW)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Intents de ação

Os seguintes intents de ação com interfaces estão disponíveis: