Google Maps para intents do Android Automotive

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

Visão geral

Nesta página, descrevemos as intents que você pode usar 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.

• 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 por URI que especificam uma ação escolhida, 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 houver vários apps disponíveis, talvez seja necessário escolher qual deles você 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 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 identificar um app que possa responder à intent, seu app pode falhar. Por isso, 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, há pelo menos um app que pode processar a intent, e é 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 guiada até o Taronga Zoo 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 para as 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 (+).

Use o método android.net.Uri encode() para codificar as strings. 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 específicos. 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 inteiro) a 21 (edifícios individuais). O limite superior pode variar de acordo com os 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 essa 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 exibir um mapa, a Pesquisa aceita este parâmetro:

• q define os lugares que serão destacados no mapa. O parâmetro q é obrigatório para todas as solicitações de pesquisa. Ele aceita um local como nome de lugar ou endereço. A string precisa ter 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 se 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 de intent direciona 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 uma intenção da pesquisa geo:latitude,longitude?q=query for enviada durante a navegação, ela vai acionar uma pesquisa ao longo da rota, 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 aceita uma intent que mostra estas categorias predefinidas:

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

Use c=<pre-defined category>, independentemente das configurações de localidade do usuário. O Google Maps mostra resultados relevantes na localidade apropriada 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);

Outras pesquisas por categoria

Se você transmitir um termo de pesquisa genérica (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 vai tentar encontrar fichas de empresas por perto. 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 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 ver 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 navegação guiada para um ou vários endereços ou coordenadas especificados. As rotas são sempre dadas 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 referência 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 endpoint como casa ou trabalho. Especifique "home" para navegar até a casa do usuário e "work" para navegar até o local de trabalho dele.

• avoid define os recursos que o trajeto 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

• 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 passagem 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 waypoints serão adicionados ao trajeto na mesma ordem em que estão listados no URL. Cada waypoint pode ser um endereço ou coordenadas de latitude e longitude separadas por vírgulas. É possível ter endereços e coordenadas de latitude e longitude na mesma intent. As strings precisam ter escape de URL. Portanto, waypoints como "Berlin,Germany|Paris,France" precisam ser convertidos em Berlin%2CGermany%7CParis%2CFrance.

Exemplos

Esta intent vai solicitar a navegação guiada 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 usar uma balsa, solicite 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);

Ou, 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 guiada para 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 Ópera de Sydney 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);

Assim como em q, é possível representar qualquer um dos waypoints por uma latitude e longitude separadas por vírgulas, em vez de um endereço. Por exemplo, para iniciar a mesma navegação, mas transmitindo a latitude e a 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 autopostos de veículos elétricos (VE). Essa intent, que estende a intent de vários pontos de referência, ajuda os motoristas a manter uma carga de bateria suficiente para chegar aos destinos, sincronizando as informações de autopostos entre os apps de planejamento de viagens de VE e o Google Maps.

Para autopostos, intenções de viagem:

• Precisa conter um nome e uma latitude/longitude.
• Pode conter 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 local 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 (PDIs) do host. Por exemplo, rotas de carro em estacionamentos ao ar livre para a parte final da navegação, horário de funcionamento, avaliações. Para garantir que as estações de recarga correspondam 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 passagem, incluindo aqueles designados como eletropostos.

Destino final

Para definir uma estação de recarga como o 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 da estação de recarga em quilowatts. Opcional.

Pontos de referência

Para waypoints, todos os parâmetros são matrizes paralelas de valores separados por barra vertical (|) na mesma ordem dos waypoints, sem incluir o destino final. Uma incompatibilidade no número de elementos em matrizes paralelas é tratada como uma intent malformada.

Para adicionar um ou mais waypoints de estações de recarga, use os seguintes parâmetros, que são todos opcionais. Se um dos destinos estiver marcado como uma estação de recarga, o nome do waypoint será obrigatório para esse destino.

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

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

• waypoint_names: nomes dos waypoints. Este campo é obrigatório para estações de recarga.

• waypoint_power_outputs_kw: números duplos 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 do waypoint, que é usado como substituto se a estação correspondente não for encontrada. Um espaço vazio significa que nenhum valor foi fornecido.

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

Para intents de viagem com vários destinos, a tela de panorama do trajeto é exibida, mas a navegação não é iniciada automaticamente.

Para uma intent formatada corretamente, o Google Maps vai apresentar uma tela de panorama do trajeto para a viagem. A tela de panorama do trajeto vai mostrar todos os pontos de referência e o destino final da intent, com recomendações de carregamento, quando aplicável.

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

• Se uma correspondência for encontrada, o Google Maps vai usar os dados do Google para mostrar a estação de recarga na interface do usuário (IU) e fornecer uma recomendação de carregamento para ela.

• Se não houver correspondência, os dados fornecidos na intent para uma estação de recarga (latitude/longitude, nome e potência) serão usados para mostrar essa estação na interface e fornecer uma recomendação de recarga nela.

Exemplos

Os exemplos a seguir mostram como criar intents para vários cenários de planejamento de viagens de VE, incluindo a navegação por várias estações de recarga e o processamento de saídas de energia desconhecidas.

Iniciar trajeto para um destino final passando por várias estações de recarga

A 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 (local: -32.9599188,151.6240806, potência: 6,6 kW)

2. Estação de recarga Evie (local: -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 de saída desconhecida

Se o valor da saída de energia for desconhecido, deixe o slot relevante de waypoint_power_outputs_kw vazio. 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 (local: -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 (local: -32.9599188,151.6240806, potência de saída: desconhecida)

3. Estação de recarga 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

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