En el mundo actual, en el que la ubicación es un factor clave, los usuarios esperan tener acceso sin problemas a la información de lugares, las instrucciones sobre cómo llegar y la navegación. Ya sea a través de una app de mensajería, una app de descubrimiento de contexto local, una plataforma de logística y transporte, un planificador de viajes o una plataforma de anuncios inmobiliarios, los usuarios suelen necesitar ver rápidamente los detalles de la ubicación o encontrar la mejor ruta de A a B. Si bien los desarrolladores pueden crear su propia experiencia en la app, aprovechar la interfaz integral y familiar de Google Maps proporciona una experiencia superior.
Una URL de Google Maps bien estructurada es fundamental para una experiencia del usuario sin inconvenientes. Las URLs incorrectas comprometen esta experiencia, ya que dirigen a los usuarios a la ubicación equivocada, muestran una vista de mapa genérica en lugar de detalles específicos o incluso generan un vínculo roto. Esto frustra a los usuarios y les impide alcanzar su objetivo. Por ejemplo, incluso con una URL de Maps válida, un usuario que espera detalles sobre una empresa específica podría llegar a una vista general del mapa sin información relevante. Consulta el siguiente ejemplo:
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
Esta URL de Maps es válida para abrir Google Maps y mostrar una ubicación según la latitud y la longitud. Sin embargo, no proporciona a los usuarios detalles sobre un lugar específico.
Cómo conectar tu aplicación con Google Maps sin problemas a través de URLs precisas
Google Maps Platform (GMP) ofrece dos métodos principales para crear URLs precisas: la API de Places(nueva), que requiere una clave de API, y las URLs de Maps, que son gratuitas y no requieren una clave. Las siguientes soluciones abordan diferentes situaciones y casos de uso:
Cómo usar los campos googleMapsUri o googleMapsLinks de la API de Places de GMP(nueva)
La API de Places de GMP(nueva) devuelve un conjunto completo de información sobre un lugar específico. Cuando se solicita el campo googleMapsUri o googleMapsLinks (especificándolo en la máscara de campo), la respuesta de la API incluye un objeto de lugar.
Este objeto contiene URLs con formato previo que se pueden usar para abrir directamente la vista correspondiente, como la vista de detalles del lugar, en Google Maps.
Ejemplo:
Solicitud de Place Details
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \ https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE
Respuesta de Place Details:
{
"googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
"googleMapsLinks": {
"directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
"placeUri": "https://maps.google.com/?cid=3545450935484072529",
"writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
"reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
"photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
}
}ChIJ3S-JXmauEmsRUcIaWtf4MzE en el ejemplo anterior es el ID de lugar de la Ópera de Sídney. Un ID de lugar es un identificador textual que identifica de forma única un lugar en la base de datos de Google Places y en Google Maps.
Cómo recuperar IDs de lugar sin costo
Para recuperar IDs de lugar de forma programática, puedes usar la función Places API: Text Search(ID Only). Este es un método sin costo para obtener IDs de lugar. Obtén más información sobre el ID de lugar y la solicitud de la API de Places(nueva).
Solicitud de Place Text Search(solo IDs) de la API de Places:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'Respuesta de Place Text Search(solo IDs) de la API de Places:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}También se pueden recuperar IDs de lugar cuando un usuario hace clic o presiona un POI en los mapas. Obtén más detalles sobre los íconos de PDI en los que se puede hacer clic(JavaScript, Android, iOS).
Implementación
Cuando usan la API de Places, los desarrolladores pueden extraer simplemente el campo googleMapsUri o googleMapsLinks de la respuesta y usarlo para iniciar la vista correspondiente en la app de Google Maps o en un navegador si la app no está instalada.
| Función | Descripción |
|---|---|
| directionsUri | Vínculo para abrir Google Maps y mostrar las instrucciones sobre cómo llegar desde la ubicación actual del usuario hasta este lugar |
| placeUri | Vínculo para abrir Google Maps en la página de detalles de este lugar |
| writeAReviewUri | Vínculo para abrir Google Maps en la página de escritura de opiniones sobre este lugar |
| reviewsUri | Vínculo para abrir Google Maps en la página de opiniones de este lugar |
| photosUri | Vínculo para abrir la página de fotos de este lugar en Google Maps |
Consulta la guía para desarrolladores y prueba la función hoy mismo.
Cómo utilizar las URLs de Maps
Con las URLs de Maps, puedes crear una URL universal multiplataforma para iniciar Google Maps, realizar búsquedas, obtener instrucciones sobre cómo llegar y de navegación, y mostrar imágenes panorámicas y vistas de mapa. La sintaxis de la URL es la misma, independientemente de la plataforma que se use. No necesitas una clave de API de Google para usar las URLs de Maps.
Las acciones disponibles en el mapa son las siguientes:
La función de búsqueda inicia una app de Google Maps o un navegador si la app no está instalada, que muestra un marcador para un lugar específico o realiza una búsqueda general y lanza un mapa para mostrar los resultados.
La función de instrucciones sobre cómo llegar inicia una app de Google Maps o un navegador (si la app no está instalada) que muestra instrucciones sobre cómo llegar entre puntos o habilita la navegación paso a paso en Google Maps para dispositivos móviles.
La función de panorámicas de Street View te permite iniciar un visor para mostrar imágenes de Street View como panorámicas interactivas.
Visita la documentación para desarrolladores de URLs de GMP Maps para explorar más funciones y ejemplos.
Aquí analizaremos dos funciones clave de las URLs de Maps:
Cómo mostrar detalles de lugares en Google Maps: En esta sección, se explica cómo crear URLs que muestren detalles de una ubicación específica en Google Maps. También se detalla cómo trabajar con lugares que tienen nombres no únicos usando IDs de lugar y búsquedas precisas.
Cómo proporcionar instrucciones para llegar con URLs de Maps: En esta sección, se explica cómo crear URLs que proporcionan instrucciones para llegar entre ubicaciones, incluidas las instrucciones con varios puntos de referencia y la navegación paso a paso.
Cómo se muestran los detalles de lugares en Google Maps
La función Search toma dos parámetros para completar la búsqueda de lugares: query(obligatorio) y query_place_id(opcional).
El parámetro query es obligatorio para todas las solicitudes de búsqueda. Acepta un nombre de lugar, coordenadas de latitud y longitud separadas por comas o un término de búsqueda general.
Estructura de la URL de la Búsqueda:
https://www.google.com/maps/search/?api=1¶meters
Situación 1: Mostrar los detalles de un lugar para un nombre de lugar único
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
Ahora considera un lugar con un nombre no único. ¿Qué sucede cuando buscas solo por este nombre no único? Consulta la siguiente situación.
Situación 2: Buscar lugares con un nombre no único
https://www.google.com/maps/search/?api=1&query=7-Eleven
Dado que el nombre del lugar no es único, esta URL abre una lista de ubicaciones cercanas de 7-Eleven dentro de la ventana gráfica. Luego, los usuarios pueden elegir una tienda específica para ver sus detalles.
Para evitar la lista de ubicaciones y acceder directamente a una página de detalles específica, puedes usar un método más preciso. Consulta el siguiente ejemplo.
Situación 3: Se muestran los detalles de un lugar con un nombre no único
Cuando se trata de nombres de lugares comunes, una búsqueda de nombres simple suele devolver una lista de ubicaciones. Para vincular directamente una página de detalles específica, puedes usar uno de los siguientes métodos:
Método 1: Usa una búsqueda precisa con el nombre y la dirección del lugar
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
En esta URL, el parámetro query tiene el formato de nombre del lugar, dirección. Esto ayuda a acotar la búsqueda y a vincular directamente a la ubicación deseada.
Método 2: Usa el ID de lugar
Los IDs de lugar identifican de forma exclusiva un lugar en la base de datos de Google Places y en Google Maps.
https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM
Aquí, ChIJGcmcg7ZC1moRAOacd3HoEwM es el ID de lugar único del lugar específico. El parámetro query sigue siendo obligatorio, pero solo se usará si Google Maps no puede encontrar el ID de lugar.
Caso 4: Cómo mostrar detalles de un lugar con coordenadas de latitud y longitud, así como el ID de lugar
El uso del ID de lugar garantiza que Google Maps muestre información detallada del lugar.
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
Cómo recuperar IDs de lugares sin costo
Para recuperar IDs de lugar de forma programática, puedes usar la función Places API: Text Search(ID Only). Este es un método sin costo para obtener IDs de lugar. Obtén más información sobre el ID de lugar y la solicitud de la API de Places(nueva).
Solicitud de Place Text Search(solo IDs) de la API de Places:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Respuesta de Place Text Search(solo IDs) de la API de Places:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}También se pueden recuperar IDs de lugar cuando un usuario hace clic o presiona un POI en los mapas. Obtén más detalles sobre los íconos de PDI en los que se puede hacer clic(JavaScript, Android, iOS).
Conclusión
Proporcionar detalles precisos del lugar es fundamental para una experiencia positiva. Para garantizar que los usuarios lleguen a la página de detalles del lugar correcta, crea las URLs de búsqueda con uno de los siguientes formatos recomendados:
query=PLACE_NAME, ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
Evita usar solo coordenadas de latitud y longitud en el parámetro query cuando tu objetivo sea mostrar los detalles de un lugar específico. Los formatos como query=latitude,longitude, query=PLACE_NAME,latitude,longitude o query=ADDRESS,latitude,longitude no siempre te llevarán a la página de detalles del lugar deseada. En su lugar, se mostrarán la latitud y la longitud de la ubicación.
Búsqueda por categorías con URLs de Maps
En una búsqueda por categorías, pasas un término de búsqueda general y Google Maps intenta encontrar fichas que coincidan con tus criterios cerca de la ubicación que especificas. Si no se especifica ninguna ubicación, Google Maps intentará encontrar fichas cerca de tu ubicación actual.
Situación 1: Búsqueda de lugares cercanos
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
Cómo proporcionar instrucciones sobre cómo llegar con URLs de Maps
La función Cómo llegar muestra la ruta entre dos o más puntos especificados en el mapa, así como la distancia y el tiempo de viaje. Ofrece a los desarrolladores más control sobre las indicaciones proporcionadas. La documentación de GMP's Maps URLs Directions proporciona instrucciones detalladas para crear URLs de instrucciones personalizadas.
Estructura de la URL de Directions:
https://www.google.com/maps/dir/?api=1¶meters
Situación 1: Cómo encontrar la mejor ruta desde la ubicación actual del usuario hasta un destino
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving
Esta URL abre Google Maps y muestra las instrucciones sobre cómo llegar en automóvil desde la ubicación actual del usuario.
En esta URL, se omite origin. Cuando se omite origin, la ruta se establece de forma predeterminada en la ubicación de inicio más pertinente, como la ubicación del dispositivo, si está disponible.
Si no hay ninguna, el mapa resultante proporciona un formulario para que el usuario ingrese el origen.
El valor del origen y el destino puede ser el nombre de un lugar, una dirección o coordenadas de latitud y longitud separadas por comas.
El parámetro travelmode es opcional. Define el método de viaje.
Este parámetro se puede establecer de la siguiente manera:
- en automóvil
- a pie
- en bicicleta
- vehículo motorizado de dos ruedas
- Tránsito
Si no se especifica ningún travelmode, el mapa de Google muestra uno o más de los modos más relevantes para la ruta especificada o las preferencias del usuario.
Los desarrolladores también pueden especificar IDs de lugar con los parámetros origin_place_id y destination_place_id. Usar un ID de lugar es la mejor garantía de que vincularás el lugar correcto.
Cómo recuperar IDs de lugares sin costo
Para recuperar IDs de lugar de forma programática, puedes usar la función Places API: Text Search(ID Only). Este es un método sin costo para obtener IDs de lugar. Obtén más información sobre el ID de lugar y la solicitud de la API de Places(nueva).
Solicitud de Place Text Search(solo IDs) de la API de Places:
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Respuesta de Place Text Search(solo IDs) de la API de Places:
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}También se pueden recuperar IDs de lugar cuando un usuario hace clic o presiona un POI en los mapas. Obtén más detalles sobre los íconos de PDI en los que se puede hacer clic(JavaScript, Android, iOS).
Situación 3: Proporcionar navegación paso a paso
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate
Si se configura dir_action=navigate en la URL, se iniciará Google Maps en el modo de navegación paso a paso si la ubicación actual del usuario(ubicación del dispositivo) está disponible y se usa como origen (ya sea que se proporcione de forma explícita o que se use de forma implícita cuando se omite el parámetro de origen). De lo contrario, se mostrará una vista previa de la ruta.
La navegación paso a paso se inicia cuando se establece dir_action=navigate y se cumplen las siguientes condiciones:
- Se especifica el origen y está cerca de la ubicación actual del usuario.
- Se omite el origen y está disponible la ubicación actual del usuario.
La vista previa de la ruta se inicia en los siguientes casos:
- No se estableció
dir_action=navigate dir_action=navigateestá configurado y se especifica el origen, y el origen no está cerca de la ubicación actual del usuariodir_action=navigateestá configurado y se omite el origen, y la ubicación actual del usuario no está disponible.
Ten en cuenta que la navegación no está disponible en todos los productos de Google Maps, como Google Maps Web, ni entre todos los destinos. En esos casos, se ignorará este parámetro.
 |
 |
Conclusión
Si construyes correctamente las URLs de Maps, puedes asegurarte de que los usuarios obtengan la información correcta que necesitan de forma rápida y eficiente.
Siempre especifica el destino y usa el ID de lugar siempre que sea posible para garantizar la precisión.
Cuando el objetivo sea proporcionar navegación inmediata, incluye el parámetro dir_action=navigate para activar la navegación paso a paso. La navegación comenzará desde la ubicación actual del usuario si la ubicación del dispositivo está disponible y se usa como origen (ya sea que se haya establecido de forma explícita o se haya omitido).
Cómo elegir el enfoque adecuado para tu aplicación
Tienes dos opciones principales: aprovechar las URLs con formato previo que proporciona la API de Places o crear manualmente URLs de Maps en tu aplicación. Cada enfoque tiene su propio conjunto de ventajas y desventajas.
API de Places:
Los campos
googleMapsUriygoogleMapsLinksde la respuesta de Place Details proporcionan URLs listas para usar, lo que reduce el tiempo de desarrollo y minimiza el riesgo de errores en el formato de las URLs.Proporciona menos control sobre la configuración de las instrucciones. Si bien
googleMapsLinksofrece instrucciones básicas, no admite puntos de referencia ni personalización avanzada. Además, es relativamente menos sencillo activar la navegación paso a paso directamente.
URLs de Maps:
Ofrece mayor flexibilidad y control. Los desarrolladores pueden crear URLs para mostrar detalles de lugares y configurar varios aspectos de las indicaciones para llegar, como agregar puntos de referencia, especificar modos de viaje y comenzar la navegación paso a paso.
Requiere una comprensión más profunda de los parámetros y la estructura de la URL. La construcción manual aumenta la posibilidad de errores si no se realiza con cuidado.
Mejora de las URLs de Maps con parámetros de UTM
Para ayudar a Google a comprender mejor cómo los desarrolladores integran las URLs de Maps y garantizar un rendimiento óptimo, te recomendamos que incluyas parámetros de seguimiento de UTM en la creación de tus URLs. Si agregas los parámetros utm_source y utm_campaign, proporcionas datos valiosos que nos permiten analizar los patrones de uso y mejorar el producto de URLs de Maps.
Para el parámetro utm_source, usa el nombre de tu aplicación. El parámetro utm_campaign debe reflejar la acción que el usuario pretende realizar, como "location_sharing", "place_details_search" o "directions_request".
Por ejemplo, una URL con parámetros UTM podría verse así:
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search
El uso constante de estos parámetros nos ayuda a identificar áreas de mejora, solucionar problemas de manera más eficaz y, en última instancia, brindar una mejor experiencia a todos los usuarios.
Próximos pasos
Lecturas adicionales sugeridas:
Colaboradores
Autores principales:
Teresa Qin | Ingeniera de soluciones de Google Maps Platform