Intents de Google Maps para Android

La app de Google Maps para Android expone varios intents que puedes usar para iniciar Google Maps en los modos de visualización, búsqueda, navegación o Street View. Para incorporar un mapa en tu app, consulta la Guía de inicio rápido de Maps SDK for Android.

En el caso de las plataformas del SO Android Automotive (AAOS), existen consideraciones específicas y intents adicionales disponibles. Consulta la documentación de Google Maps para Android Automotive Intents para obtener más detalles.

Descripción general

Los intents te permiten iniciar una actividad en otra app. Para ello, debes describir una acción que desees realizar (como "mostrar un mapa" o "mostrar instrucciones sobre cómo llegar al aeropuerto") en un Intent objeto. La app de Google Maps para Android admite varios intents diferentes,lo que te permite iniciar la app de Google Maps y realizar una de las siguientes cuatro acciones:

1. Mostrar un mapa en una ubicación y a un nivel de zoom especificados.
2. Buscar ubicaciones o lugares y mostrarlos en un mapa.
3. Solicitar indicaciones para ir de una ubicación a otra. Se pueden mostrar instrucciones sobre cómo llegar para tres modos de transporte: en automóvil, a pie y en bicicleta.
4. Mostrar imágenes panorámicas en Google Street View.

En esta página, se describen los intents que puedes usar con la app de Google Maps para Android. Para obtener más información sobre los intents, consulta Intents y filtros de intents y Intents comunes.

Solicitudes de intents

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

• Acción: Todos los intents de Google Maps se llaman como una acción de vista: ACTION_VIEW.
• URI: Los intents de Google Maps usan URIs codificados como URL que especifican una acción seleccionada, junto con algunos datos con los que se realizará la acción.

• Paquete: Si llamas a setPackage("com.google.android.apps.maps"), te aseguras de 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 le pregunte al usuario cuál desea 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 startActivity() método. El sistema inicia la app necesaria — en este caso, Google Maps— y comienza la Activity correspondiente.

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

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

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 se haya instalado una aplicación receptora antes de presentar uno de estos intents a un usuario.

Para verificar que haya una app disponible para recibir el intent, llama a resolveActivity() en tu Intent objeto. 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 null, no uses el intent y, si es posible, inhabilita la función que lo invoca.

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

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

Por ejemplo, para mostrar un mapa de San Francisco puedes usar el siguiente código:

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

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

Cadenas de consulta codificadas como URL

Todas las cadenas pasadas a las intenciones de Google Maps deben tener codificación de URI. Por ejemplo, la cadena 1st & Pike, Seattle debe 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 android.net.Uri encode() método para codificar tus cadenas. Por ejemplo:

Uri gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

Muestra un mapa

Usa el intent geo: para mostrar un mapa en una ubicación y a un nivel de zoom especificados.

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.

Ejemplos

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

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

Buscar una ubicación

Usa esta intención para mostrar solicitudes de búsqueda dentro de un viewport especificado. Cuando la consulta tiene un solo resultado, puedes usar este intent para mostrar un pin en un lugar o una dirección en particular, como un punto de referencia, una empresa, un elemento geográfico, o una ciudad.

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

Parámetros

Además de los parámetros que se usan para mostrar un mapa, la búsqueda admite los siguientes parámetros:

• 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 estar codificada como URL, por lo que una dirección como City Hall, New York, NY debe convertirse en City+Hall,New+York,NY.

• label te permite establecer una etiqueta personalizada en un lugar identificado en el mapa. El label debe especificarse como una cadena.

Búsqueda por categoría

Si pasas un término de búsqueda general, Google Maps intenta encontrar una ubicación cerca de la latitud y la longitud que especificaste que coincida con tus criterios. Si no se especifica ninguna ubicación, Google Maps intenta encontrar fichas 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);
// 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);

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

Puedes sesgar aún más los resultados de la búsqueda si especificas un parámetro de zoom junto con la cadena de consulta. En el siguiente ejemplo, si agregas un zoom de 10, se 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);

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)

Búsqueda por ubicación

Si buscas una dirección específica, se muestra un pin en esa ubicación.

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

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)

En el ejemplo anterior, se establece una latitud y una longitud de 0,0, pero se pasa una dirección como cadena de consulta. Cuando buscas una ubicación específica, no se requieren la latitud ni la longitud. Sin embargo, si no conoces la dirección exacta, puedes intentar sesgar los resultados de la búsqueda especificando una coordenada. Por ejemplo, si realizas una búsqueda de dirección para "Main Street", es posible que se muestren demasiados resultados.

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

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

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

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

Cuando sabes que tu búsqueda muestra un solo valor, es posible que desees pasar una etiqueta opcional. Las etiquetas deben especificarse como una cadena y aparecer debajo del marcador del mapa. Ten en cuenta que las etiquetas solo están disponibles cuando q se especifica como una coordenada de latitud y longitud.

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

// 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 una dirección o una latitud y longitud, puedes mostrar un pin en una ubicación conocida con un Plus Code.

// 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.

// 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.

Inicia la navegación paso a paso

Usa este URI del intent para iniciar la navegación de Google Maps con instrucciones paso a paso para la dirección o la coordenada especificadas. Las instrucciones siempre se dan desde la ubicación actual del usuario.

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

Parámetros

• q: Establece el extremo para las búsquedas de navegación. Este valor puede ser coordenadas de latitud y longitud o una dirección con formato de consulta. Si es una cadena de consulta que muestra más de un resultado, se selecciona el primero.

• mode establece el método de transporte. mode es opcional y se puede configurar en una de las siguientes opciones:

  • d para conducir (predeterminado)
  • b para andar en bicicleta
  • l para vehículos de dos ruedas
  • w para caminar

• avoid establece las funciones que la ruta debe intentar evitar. avoid es opcional y se puede configurar en una o más de las siguientes opciones:

  • t para peajes
  • h para autopistas
  • f para ferries

Ejemplos

Las siguientes solicitudes de Intent activan la navegación paso a paso al zoológico de Taronga, en Sídney, Australia:

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

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)

Si prefieres no pagar peajes ni viajar en ferry, puedes solicitar una ruta que intente evitar esas funciones.

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

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)

Si prefieres hacer un poco de ejercicio, puedes solicitar instrucciones para andar en bicicleta.

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

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)

Si prefieres tomar un vehículo de dos ruedas motorizado, puedes solicitar que las instrucciones incluyan caminos y senderos estrechos que no estén disponibles para los automóviles. El siguiente intent muestra una ruta en India.

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

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)

Muestra una panorámica de Street View

Usa el intent google.streetview para iniciar Google Street View. Google Street View proporciona vistas panorámicas desde ubicaciones designadas en su área de cobertura. También están disponibles las fotos esféricas aportadas por los usuarios, y las colecciones especiales de Street View.

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

Parámetros

Todos los URIs de google.streetview deben incluir un parámetro cbll o panoid:

• cbll acepta una latitud y una longitud como valores separados por comas (46.414382,10.013988). La app muestra la panorámica fotografiada más cerca de esta ubicación. Debido a que las imágenes de Street View se actualizan periódicamente y las fotografías se pueden tomar desde posiciones ligeramente diferentes cada vez, es posible que tu ubicación se ajuste a una panorámica diferente cuando se actualicen las imágenes.

• panoid es un ID de panorámica específico. Google Maps usa el ID de panorámica si se especifican un panoid y un cbll. Los IDs de panorámica están disponibles para una app para Android desde el StreetViewPanoramaLocation objeto.

• cbp es un parámetro opcional que ajusta la orientación inicial de la cámara. El parámetro cbp toma 5 valores separados por comas, todos los cuales son opcionales. Los valores más significativos son el segundo, el cuarto y el quinto que establecen la orientación, el zoom y la inclinación, respectivamente. No se admiten el primer y el tercer valor, y deben establecerse en 0.

  • bearing: Indica la orientación de la brújula de la cámara en grados en el sentido de las agujas del reloj desde el norte. El norte verdadero es 0, el este es 90, el sur es 180 y el oeste es
    1. Los valores que se pasan a la orientación se ajustan; es decir, 0°, 360° y 720° apuntan en la misma dirección. La orientación se define como el segundo de cinco valores separados por comas.
  • zoom: Establece el nivel de zoom de la cámara. El nivel de zoom predeterminado se establece en 0. Un valor 1 de zoom duplicaría la magnificación. El zoom se fija entre 0 y el nivel de zoom máximo para la panorámica actual. Esto significa que cualquier valor que quede fuera de este rango se establece en el extremo más cercano que se encuentre dentro del rango. Por ejemplo, un valor de -1 se establece en 0. El zoom es el cuarto de los valores separados por comas.
  • tilt: Especifica el ángulo, hacia arriba o hacia abajo, de la cámara. El rango es de -90 a 0 y 90, donde 90 representa la posición extrema inferior, 0 la posición centrada en el horizonte y -90 la posición extrema superior.

Ejemplos

A continuación, se muestran algunos ejemplos del uso del intent de Street View.

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

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