Intents de Google Maps para Android Automotive

A través de intents de Android, puedes iniciar la navegación en Google Maps para Android Automotive.

Descripción general

En esta página, se describen los intents que puedes usar con Google Maps para Android Automotive. Para obtener documentación detallada para desarrolladores de Android, consulta lo siguiente:

• Intents y filtros de intents
• Intents comunes a la plataforma de Android

Solicitudes de intención

Para iniciar Google Maps para Android Automotive con un intent, primero debes crear un objeto Intent y especificar su acción, URI y paquete.

• Acción. Todos los intents de Google Maps se llaman como una acción de View, ACTION_VIEW.

• URI. Los intents de Google Maps usan cadenas codificadas con URI que especifican una acción elegida, junto con algunos datos con los que se realizará la acción.

• Paquete. La llamada a setPackage("com.google.android.apps.maps") garantiza que la app de Google Maps para Android controle el Intent. Si no se configura el paquete, el sistema determina qué apps pueden controlar el Intent. Si hay varias apps disponibles, es posible que se te pregunte cuál quieres usar.

Después de crear el Intent, puedes solicitar que el sistema inicie la app relacionada de varias maneras. Un método común es pasar el Intent al método startActivity(). El sistema iniciará la app necesaria, en este caso, Google Maps, y comenzará la Activity correspondiente.

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

Si el sistema no puede identificar una app que pueda responder al Intent, es posible que tu app falle. Por este motivo, primero verifica que haya una aplicación receptora instalada antes de presentar una de estas intents al usuario.

Para verificar que una app esté disponible para recibir el intent, llama a resolveActivity() en tu objeto Intent. Si el resultado no es nulo, hay al menos una app que puede controlar el intent y es seguro llamar a startActivity(). Si el resultado es nulo, no debes usar el intent y, si es posible, debes inhabilitar la función que invoca el intent.

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

Por ejemplo, para iniciar la navegación paso a paso hacia el zoológico de Taronga en Sídney, puedes usar el siguiente 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);
}

Cadenas de consulta codificadas como URI

Todas las cadenas que se pasan a los intents de Google Maps deben estar codificadas como URI. Por ejemplo, la cadena "1st & Pike, Seattle" debería convertirse en 1st%20%26%20Pike%2C%20Seattle. Los espacios de la cadena se pueden codificar con %20 o reemplazar con el signo más (+).

Puedes usar el método android.net.Uri encode() para codificar tus cadenas. Por ejemplo:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

Cómo mostrar un mapa

Usa el intent geo: para mostrar un mapa en una ubicación y con un nivel de zoom específicos. Por ejemplo:

geo:latitude,longitude?z=zoom

Parámetros

• latitude y longitude establecen el punto central del mapa.

• z establece de forma opcional el nivel de zoom inicial del mapa. Los valores aceptados varían de 0 (todo el mundo) a 21 (edificios individuales). El límite superior puede variar según los datos del mapa disponibles en la ubicación seleccionada.

Ejemplo

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

Buscar una ubicación

Usa este intent para mostrar búsquedas dentro de una ventana gráfica especificada:

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

Parámetros

Además de los parámetros que se usan para mostrar un mapa, la Búsqueda admite el siguiente parámetro:

• q define los lugares que se destacarán en el mapa. El parámetro q es obligatorio para todas las solicitudes de búsqueda. Acepta una ubicación como nombre de lugar o dirección. La cadena debe tener caracteres de escape de URL, por lo que una dirección como "City Hall, New York, NY" debe convertirse en City+Hall%2CNew+York%2CNY.

Cómo personalizar los resultados de la búsqueda con coordenadas

Cuando se busca una ubicación muy específica, la latitud y la longitud no son estrictamente necesarias si se incluyen en el parámetro q. Sin embargo, si no conoces la dirección exacta o la búsqueda es ambigua, puedes intentar sesgar los resultados de la búsqueda especificando una coordenada. Por ejemplo, realizar una búsqueda de dirección para "calle principal" podría devolver demasiados 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);

Si agregas una latitud y una longitud al URI del intent, los resultados se sesgan hacia un área en particular:

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

Buscar en la ruta

Si se envía una intención de búsqueda geo:latitude,longitude?q=query durante la navegación, se activa una búsqueda a lo largo de la ruta y se ignoran la latitud y la longitud.

Cómo buscar categorías predefinidas

Para admitir la integración con el vehículo, Google Maps en el automóvil admite una intención que muestra estas categorías predefinidas:

La intención de categoría tiene el formato geo:lat,lng?c=category.

Usa c=<pre-defined category> independientemente de la configuración regional del usuario. Google Maps muestra resultados relevantes en la configuración regional adecuada para esta categoría. Por ejemplo:

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

Otras búsquedas por categoría

Si pasas un término de búsqueda general (como "restaurantes" o "cafeterías") en la configuración regional del usuario, Google Maps para Android Automotive buscará fichas de empresas que coincidan con los criterios. Si se proporcionan una latitud y una longitud específicas en el intent geo:, la búsqueda se centra en esa ubicación. Si no se especifica ninguna ubicación (p.ej., geo:0,0), Google Maps intenta encontrar fichas de empresas cercanas. Por ejemplo:

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

Puedes personalizar aún más los resultados de la búsqueda si especificas un parámetro de zoom junto con la cadena de búsqueda. En el siguiente ejemplo, agregar un zoom de 10 intenta encontrar restaurantes a nivel de la ciudad en lugar de cerca:

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

Inicia la navegación paso a paso

Para obtener documentación sobre cómo iniciar la navegación paso a paso en otros dispositivos Android, consulta Cómo iniciar la navegación paso a paso en Intents de Google Maps para Android.

Usa esta intención para iniciar la navegación de Google Maps con instrucciones paso a paso a una o varias direcciones o coordenadas especificadas. Las indicaciones siempre se dan desde la ubicación actual del usuario.

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

Parámetros

Para iniciar la navegación, usa place o q con waypoints, que es opcional. Para marcar de forma opcional una parada como estación de carga, consulta Cómo enviar un plan de viaje en vehículo eléctrico a Google Maps.

• q establece el extremo para las búsquedas de navegación. Puede ser una latitud y una longitud, o una dirección con formato de consulta. Si es una cadena de búsqueda que devuelve más de un resultado, se seleccionará el primero.

• place establece el punto final en tu dirección particular o de trabajo. Especifica home para navegar a la casa del usuario y work para navegar a su lugar de trabajo.

• avoid establece las características que la ruta debe intentar evitar. avoid es opcional y se puede establecer en uno o más de los siguientes valores:

  • t para peajes
  • h para autopistas
  • f para ferris

• waypoints especifica uno o más lugares intermedios para generar instrucciones sobre cómo llegar al destino final especificado por q. Puedes especificar varias paradas intermedias con el carácter de barra vertical (|) para separar lugares, por ejemplo, Berlin,Germany|Paris,France. Puedes usar tantos puntos de referencia como necesites. Los puntos de ruta se agregarán a la ruta en el mismo orden en que aparecen en la URL. Cada punto de referencia puede ser una dirección o coordenadas de latitud y longitud separadas por comas. Además, puedes tener direcciones y coordenadas de latitud y longitud en la misma intención. Las cadenas deben tener escape de URL, por lo que los puntos de referencia como "Berlín,Alemania|París,Francia" deben convertirse en Berlin%2CGermany%7CParis%2CFrance.

Ejemplos

Esta intención solicitará navegación paso a paso al zoológico de Taronga, en Sídney, Australia:

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

Si prefieres no pagar peajes ni viajar en ferry, puedes solicitar una ruta que intente evitar estas situaciones:

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

Si prefieres navegar a tu casa, usa lo siguiente:

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 la navegación paso a paso a las siguientes tres direcciones en orden, pasa el zoológico de Taronga como el destino final q y Google Sydney y la Ópera de Sídney como los puntos de referencia:

1. Google Sídney

2. Ópera de Sídney

3. Zoológico de Taronga, Sídney, Australia

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

Al igual que con q, puedes representar cualquiera de los puntos de referencia con una latitud y una longitud separadas por comas en lugar de una dirección. Por ejemplo, para iniciar la misma navegación y pasar la latitud y la longitud de la Ópera de Sídney en lugar de la dirección, haz lo siguiente:

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

Cómo enviar un plan de viaje en vehículo eléctrico a Google Maps

Usa esta intención de navegación con varios destinos para especificar algunos destinos como paradas de carga de vehículos eléctricos (VE). Esta intención, que extiende la intención de varios puntos de referencia, ayuda a los conductores a mantener una carga de batería suficiente en el vehículo eléctrico para llegar a sus destinos, ya que sincroniza la información de las paradas de carga entre las apps de planificación de viajes en VE y Google Maps.

Para las paradas de carga, las intenciones de viaje son las siguientes:

• Debe contener un nombre y una latitud y longitud
• Puede contener, de forma opcional, una potencia de salida que se usará para calcular el tiempo de carga.

Google usa el nombre y la latitud y longitud de la estación de carga para encontrar un lugar de estación de carga coincidente y mostrar datos enriquecidos, como los tipos de conector, los totales, las velocidades y la disponibilidad en tiempo real, las formas de pago admitidas y los puntos de interés (POI) del host. Por ejemplo, instrucciones para llegar en auto dentro de estacionamientos al aire libre para la parte final de la navegación, horarios de atención y calificaciones. Para asegurarte de que las estaciones de carga coincidan bien con los datos de Google, usa un <brand name> específico, por ejemplo, ChargePoint.

Parámetros

Los siguientes parámetros te permiten especificar detalles del destino final y de cualquier punto de referencia, incluidos los que se designan como estaciones de carga de VE.

Destino final

Para establecer una estación de carga como destino final, usa lo siguiente:

• q: Debe contener el valor de latitud y longitud de la estación de carga.
• q_type: 1 especifica que el destino final es una estación de carga.
• q_name: Es el nombre del destino final. Obligatorio si q_type es 1.
• q_power_output_kw: Es un número doble que indica la potencia de salida de la estación de carga en kilovatios. Opcional.

Waypoints

En el caso de las paradas intermedias, todos los parámetros son arreglos paralelos separados por barras verticales (|) de valores en el mismo orden que las paradas intermedias, sin incluir el destino final. Una discrepancia en la cantidad de elementos de los arrays paralelos se considera una intención con formato incorrecto.

Para agregar uno o más puntos de ruta de estaciones de carga, usa los siguientes parámetros, todos opcionales. Si uno de los destinos está marcado como estación de carga, el nombre del punto de referencia se vuelve obligatorio para ese destino.

• waypoints: Es la lista de puntos de referencia como se describe en la intención de navegación paso a paso. Debe ser un valor de latitud y longitud para las paradas de las estaciones de carga.

• waypoint_types: Tipos por punto de referencia especificados como un número. 0 es cualquier parada (valor predeterminado) y 1 es la estación de carga.

• waypoint_names: Nombres de los puntos de ruta. Este campo es obligatorio para las estaciones de carga.

• waypoint_power_outputs_kw: Números dobles para la potencia de la estación de carga en kilovatios. En el caso de las estaciones de carga, puedes especificar de forma opcional un valor de potencia de salida del punto de ruta, que se usa como alternativa si no se encuentra la estación correspondiente. Una ranura vacía significa que no se proporcionó ningún valor.

Comportamiento de la experiencia del usuario (UX)

En el caso de las intenciones de viaje con varios destinos, se muestra la pantalla de resumen de la ruta, pero la navegación no se inicia automáticamente.

En el caso de una intención con el formato correcto, Google Maps mostrará una pantalla de resumen de la ruta del viaje. En la pantalla de resumen de la ruta, se mostrarán todos los puntos de referencia y el destino final del propósito, con recomendaciones de carga cuando corresponda.

En el caso de las paradas o el destino final marcados como estaciones de carga, Google Maps buscará un lugar coincidente en la base de datos de Google. Para garantizar que se muestre la mejor información posible sobre las estaciones de carga, haz lo siguiente:

• Si se encuentra una coincidencia, Google Maps usa los datos de Google para mostrar la estación de carga en la interfaz de usuario (IU) y proporcionar una recomendación de carga para la estación.

• Si no se encuentra la coincidencia, se usan los datos proporcionados en la intención para una estación de carga (latitud y longitud, nombre y potencia de salida) para mostrar esta estación de carga en la IU y proporcionar una recomendación de carga en esta estación.

Ejemplos

En los siguientes ejemplos, se ilustra cómo construir intents para diversas situaciones de planificación de viajes en VE, incluida la navegación a través de varias estaciones de carga y el control de salidas de potencia desconocidas.

Navegar a un destino final pasando por varias estaciones de carga

La siguiente intención navega al destino final, Port Macquarie NSW, a través de dos estaciones de carga, ChargePoint y Evie.

Destinos en orden:

1. Estación de carga ChargePoint (ubicación: -32.9599188,151.6240806, potencia de salida: 6.6 kW)

2. Estación de carga de Evie (ubicación: -31.9432539,152.4699808, potencia de salida: 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);

Potencia de salida desconocida

Si se desconoce el valor de potencia de salida, deja vacío el espacio correspondiente de waypoint_power_outputs_kw. O bien, si todas las ranuras están vacías, no es necesario especificar el parámetro waypoint_power_outputs_kw.

Destinos en orden:

1. Estación de carga ChargePoint (ubicación: -32.9599188,151.6240806, potencia de salida: desconocida)

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

Cómo marcar el destino final como una estación de carga

Para marcar el destino final como una estación de carga, especifica los parámetros q_type, q_name y q_power_output_kw.

Destinos en orden:

1. Zoológico de Taronga, Sídney, Australia

2. Estación de carga ChargePoint (ubicación: -32.9599188,151.6240806, potencia: desconocida)

3. Estación de carga Evie (ubicación: -31.9432539,152.4699808, potencia de salida: 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 acción

Están disponibles los siguientes intents de acción con interfaces: