Pronto habrá nuevas opciones para el diseño de mapas disponibles en Google Maps Platform. Esta actualización del diseño de mapas incluye una nueva paleta de colores predeterminada, así como mejoras en la experiencia y la usabilidad del mapa. Todos los diseños de mapa se actualizarán automáticamente en marzo de 2025. Para obtener más información sobre la disponibilidad y cómo habilitar esta actualización antes, consulta Nuevo diseño de mapa para Google Maps Platform.
En esta página, se describe la biblioteca del cliente disponible con la API de Maps JavaScript. Si deseas trabajar con el servicio web de la API de Places en tu servidor, consulta Cliente de Node.js para los servicios de Google Maps. En la página de ese vínculo, también se muestra información sobre los clientes de Java, Python y Go para los servicios de Google Maps.
Introducción
Autocomplete es una función de la biblioteca de Places de la API de Maps JavaScript. Puedes usar esta función para incluir en tus aplicaciones el comportamiento de escritura anticipada del campo de búsqueda de Google Maps.
El servicio de autocompletado puede buscar coincidencias para palabras completas y subcadenas para resolver nombres de lugares, direcciones y Plus Codes. Así, las aplicaciones pueden enviar búsquedas a medida que el usuario escribe para proporcionar predicciones de lugares en el momento. Según se define en la API de Places, un "lugar" puede ser un establecimiento, una ubicación geográfica o un lugar de interés destacado.
Primeros pasos
Antes de usar la biblioteca de Places en la API de Maps JavaScript, asegúrate de que esté habilitada en la consola de Google Cloud, en el mismo proyecto que configuraste para la API de Maps JavaScript.
Para ver tu lista de APIs habilitadas, haz lo siguiente:
Haz clic en el botón Seleccionar un proyecto, selecciona el mismo proyecto que configuraste para la API de Maps JavaScript y haz clic en Abrir.
En la lista de APIs del Panel, busca API de Places.
Si ves la API en la lista, no necesitas hacer nada más. Si la API no está en la lista, habilítala:
En la parte superior de la página, selecciona HABILITAR API para abrir la pestaña Biblioteca. También puedes seleccionar Biblioteca en el menú lateral izquierdo.
Busca la opción API de Places y selecciónala en la lista de resultados.
Selecciona HABILITAR. Cuando finalice el proceso, aparecerá la opción API de Places en la lista de APIs del Panel.
Cómo cargar la biblioteca
El servicio Places es una biblioteca independiente, separada del código principal de la API de Maps JavaScript. Para usar la funcionalidad contenida en esta biblioteca, primero debes cargarla con el parámetro libraries en la URL de arranque de la API de Google Maps:
La API ofrece dos tipos de widgets de autocompletado que puedes agregar mediante las clases Autocomplete y SearchBox, respectivamente.
Además, puedes usar la clase AutocompleteService para recuperar resultados de autocompletado de manera programática (consulta la referencia de la API de Maps JavaScript: clase AutocompleteService).
A continuación, se ofrece un resumen de las clases disponibles:
Autocomplete agrega un campo de entrada de texto a tu página web y supervisa las entradas de caracteres en ese campo. A medida que el usuario ingresa texto, el autocompletado muestra predicciones de lugares en forma de una lista de selección desplegable. Cuando el usuario selecciona un lugar de la lista, se envía información sobre el lugar al objeto de autocompletado, y la aplicación la recibe. Consulta más detalles a continuación.
Imagen 1: Campo de autocompletado de texto y lista de selecciónImagen 2: Formulario de dirección completo
SearchBox agrega un campo de entrada de texto a tu página web, de manera similar a lo que sucede con Autocomplete. Las diferencias se muestran a continuación:
La diferencia principal radica en los resultados que aparecen en la lista de selección. SearchBox proporciona una lista extendida de predicciones, que puede incluir lugares (según lo establecido en la API de Places) y términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza en nueva", la lista de selección puede incluir "pizza en Nueva York, NY" y los nombres de varias pizzerías.
SearchBox ofrece menos opciones que Autocomplete para restringir la búsqueda. En el primero, es posible personalizar la búsqueda en función de un objeto LatLngBounds determinado. En el segundo, en cambio, puedes restringir la búsqueda a un país y un tipo de lugar determinados, así como configurar límites. Para obtener más información, consulta lo siguiente.
Imagen 3: Un cuadro de búsqueda muestra términos de búsqueda y predicciones de lugares.Consulta más detalles a continuación.
Puedes crear un objeto AutocompleteService para obtener predicciones de manera programática. Llama a getPlacePredictions() para obtener los lugares coincidentes, o bien a getQueryPredictions() para obtener los lugares coincidentes y los términos de búsqueda sugeridos.
Nota: AutocompleteService no agrega ningún control de IU.
En cambio, los métodos anteriores muestran un array de objetos de predicción. Cada objeto de predicción contiene el texto de la predicción, así como información de referencia y detalles sobre la coincidencia entre el resultado y la entrada del usuario. Consulta los detalles a continuación.
Cómo agregar un widget de Autocomplete
El widget de Autocomplete crea un campo de entrada de texto en tu página web, proporciona predicciones de lugares en una lista de selección de la IU y muestra detalles de lugares como respuesta a cada solicitud de getPlace(). Cada entrada de la lista de selección corresponde a un solo lugar (según lo que establece la API de Places).
El constructor Autocomplete toma dos argumentos:
Un elemento HTML input de tipo text: El servicio de autocompletado controla este campo de entrada y le adjunta sus resultados.
Un argumento AutocompleteOptions opcional que puede incluir las siguientes propiedades:
Un array de datos fields que se incluirá en la respuesta Place Details para el PlaceResult seleccionado por el usuario. Si la propiedad no está configurada, o si se pasa ['ALL'], se muestran y se facturan todos los campos disponibles (esto no se recomienda en las implementaciones de producción). Para obtener una lista de campos, consulta PlaceResult
Un array de types que especifica un tipo explícito o una colección de tipos, como se indica en los tipos compatibles. Si no se especifica un tipo, se muestran todos
bounds es un objeto google.maps.LatLngBounds que especifica el área en la que se buscarán lugares. Los resultados se personalizan, aunque no de manera exclusiva, conforme a estos límites
strictBounds es un boolean que especifica si la API debe mostrar solo los lugares que están estrictamente dentro de la región definida por el bounds especificado. La API no muestra resultados fuera de esta región, aun si coinciden con la entrada del usuario
.
componentRestrictions se puede usar para restringir los resultados a grupos específicos. Actualmente, puedes utilizar componentRestrictions para filtrar por un máximo de 5 países. Los países se deben pasar como un código de país ISO 3166-1 Alfa-2 compatible de dos caracteres. Si se pasan varios países, se deben utilizar listas de códigos de país
Nota: Si recibes resultados inesperados con un código de país, verifica si el código utilizado incluye los países, los territorios dependientes y las áreas especiales de interés geográfico que deseas. Puedes encontrar información sobre el código en Wikipedia: Lista de códigos de país ISO 3166 o en la Plataforma de navegación en línea ISO.
placeIdOnly se puede usar para indicarle al widget Autocomplete que recupere solo los IDs de lugar. Cuando llames a getPlace() en el objeto Autocomplete, el PlaceResult disponible solo tendrá configuradas las propiedades place id, types y name. Puedes usar el ID de lugar que se muestra con las llamadas a los servicios Places, Geocoding, Directions o Distance Matrix
Cómo restringir las predicciones de Autocomplete
De forma predeterminada, Place Autocomplete presenta todos los tipos de lugares, personalizados según la ubicación del usuario, y obtiene información de todos los campos de datos disponibles para el lugar que este selecciona. Configura las opciones de Place Autocomplete para presentar predicciones más relevantes según tu caso de uso.
Establece opciones durante la construcción
El constructor Autocomplete acepta un parámetro AutocompleteOptions para establecer restricciones en la creación del widget. En el siguiente ejemplo, se configuran las opciones bounds, componentRestrictions y types para solicitar lugares de tipo establishment de modo que se prioricen aquellos ubicados dentro del área geográfica especificada y se restrinjan las predicciones a los lugares dentro de Estados Unidos únicamente. Configurar la opción fields permite especificar qué información se mostrará sobre el lugar seleccionado por el usuario.
Llama a setOptions() para cambiar el valor de una opción para un widget existente.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
Especifica los campos de datos si deseas evitar que se te facturen los SKUs de datos de lugares que no necesitas. Incluye la propiedad fields en las AutocompleteOptions que se pasan al constructor del widget, como se demostró en el ejemplo anterior, o llama a setFields() en un objeto Autocomplete existente.
Establece personalizaciones y límites de área de búsqueda para Autocomplete
Puedes personalizar los resultados de autocompletado para priorizar una ubicación o un área aproximadas de las siguientes maneras:
Configura los límites durante la creación del objeto Autocomplete.
Cambia los límites en un objeto Autocomplete existente.
Configura los límites del viewport del mapa.
Restringe la búsqueda a los límites.
Restringe la búsqueda a un país específico.
En el ejemplo anterior, se muestra cómo configurar límites durante la creación. Los siguientes ejemplos demuestran las demás técnicas de personalización.
Cambia los límites en un objeto de Autocomplete existente
Llama a setBounds() para cambiar el área de búsqueda de un objeto Autocomplete existente a límites rectangulares.
Configura la opción strictBounds para restringir los resultados a los límites actuales, ya sea en función del viewport del mapa o los límites rectangulares.
autocomplete.setOptions({ strictBounds: true });
Restringe las predicciones a un país específico
Usa la opción componentRestrictions o llama a setComponentRestrictions() para restringir la búsqueda de autocompletado a un conjunto específico de hasta cinco países.
Usa la opción types o llama a setTypes() para restringir las predicciones a ciertos tipos de lugares. Esta restricción especifica un tipo o un conjunto de tipos, según lo que se indica en Tipos de lugares.
Si no se indica ninguna restricción, se muestran todos los tipos.
Para el valor de la opción types o el valor que se pasa a setTypes(), puedes especificar lo siguiente:
Cuando un usuario selecciona un lugar entre las predicciones que se adjuntan al campo de texto de autocompletado, el servicio activa un evento place_changed. Para obtener detalles del lugar, haz lo siguiente:
Crea un controlador para el evento place_changed y llama a addListener() en el objeto Autocomplete para agregarlo al controlador.
Llama a Autocomplete.getPlace() en el objeto Autocomplete para obtener un objeto PlaceResult, el cual puedes usar para obtener más información sobre el lugar seleccionado.
De forma predeterminada, cuando un usuario selecciona un lugar, el autocompletado propaga todos los campos de datos disponibles para el lugar seleccionado, y la facturación se realiza en función de ello.
Usa Autocomplete.setFields() para especificar qué campos de datos de lugar deseas que se completen. Obtén más información sobre el objeto PlaceResult, incluida una lista de los campos de datos de lugar que puedes solicitar. Para evitar pagar por datos que no necesitas, asegúrate de usar Autocomplete.setFields() para especificar los datos de lugar que deseas utilizar.
La propiedad name contiene el description de las predicciones de Place Autocomplete. Puedes obtener más información sobre description en la documentación de Place Autocomplete.
Para los formularios de dirección, es útil obtener la dirección en formato estructurado. Para mostrar la dirección estructurada para el lugar seleccionado, llama a Autocomplete.setFields() y especifica el campo address_components.
En el siguiente ejemplo, se usa la función de autocompletado para completar los campos de un formulario de dirección.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
document.querySelector("#locality").value = component.long_name;
break;
case "administrative_area_level_1": {
document.querySelector("#state").value = component.short_name;
break;
}
case "country":
document.querySelector("#country").value = component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
window.initAutocomplete = initAutocomplete;
Cómo personalizar el texto del marcador de posición
De manera predeterminada, el campo de texto creado por el servicio de autocompletado contiene texto estándar con marcadores de posición. Para modificar el texto, configura el atributo placeholder en el elemento input:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Nota: El texto predeterminado del marcador de posición se localiza automáticamente. Si especificas tu propio valor de marcador de posición, deberás administrar la localización correspondiente en tu aplicación. Para obtener información sobre cómo la API de Google Maps JavaScript selecciona el idioma que se usará, consulta la documentación sobre la localización.
El SearchBox permite a los usuarios realizar una búsqueda geográfica basada en texto, como "pizza en Nueva York" o "tiendas de zapatos cerca de la calle robson".
Puedes adjuntar SearchBox a un campo de texto y, a medida que el usuario ingrese el texto, el servicio mostrará predicciones en forma de lista de selección desplegable.
SearchBox proporciona una lista extendida de predicciones, que puede incluir lugares (según lo que define la API de Places), así como términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza en nueva", en la lista de selección puede incluirse "pizza en Nueva York, NY" y los nombres de varias pizzerías. Cuando un usuario selecciona un lugar de la lista, la información sobre ese lugar se proporciona al objeto SearchBox, y tu aplicación puede recuperarla.
El constructor SearchBox toma dos argumentos:
Un elemento HTML input de tipo text: El servicio de SearchBox controla este campo de entrada y le adjunta sus resultados.
Un argumento options, que puede contener la propiedad bounds: bounds es un objeto google.maps.LatLngBounds que especifica el área en la que se buscarán lugares. Los resultados se personalizan, aunque no de manera exclusiva, conforme a estos límites.
En el siguiente código se usa el parámetro bounds para personalizar los resultados en función de los lugares de una ubicación geográfica en particular, la cual se especifica a través de coordenadas de latitud y longitud.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
Cómo cambiar el área de búsqueda de SearchBox
Para cambiar el área de búsqueda de un SearchBox existente, llama a setBounds() en el objeto SearchBox y pasa el objeto LatLngBounds relevante.
Cuando el usuario selecciona un elemento de las predicciones que se adjuntan al cuadro de búsqueda, el servicio activa un evento places_changed. Puedes llamar a getPlaces() en el objeto SearchBox para obtener un array con diversas predicciones, cada una de las cuales es un objeto PlaceResult.
Para obtener más información sobre el objeto PlaceResult, consulta la documentación sobre los resultados de detalles de lugar.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
}),
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
Cómo recuperar de forma programática las predicciones del servicio Place Autocomplete
Para recuperar predicciones de forma programática, usa la clase AutocompleteService. AutocompleteService no agrega ningún control de la IU. En cambio, muestra un array de objetos de predicción, cada uno de los cuales contiene el texto de la predicción, así como información de referencia y detalles sobre la coincidencia entre el resultado y la entrada del usuario.
Esto es útil si deseas tener más control sobre la interfaz de usuario que el que ofrecen las funciones Autocomplete y SearchBox descritas anteriormente.
AutocompleteService expone los siguientes métodos:
getPlacePredictions() muestra predicciones de lugar.
Nota: Un "lugar" puede ser un establecimiento, una ubicación geográfica o un lugar de interés destacado, según lo que define la API de Places.
getQueryPredictions() muestra una lista extendida de predicciones, que puede incluir lugares (según lo que define la API de Places) y términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza en nueva", en la lista de selección puede incluirse "pizza en Nueva York, NY" y los nombres de varias pizzerías.
distance_meters es la distancia en metros entre lugar y el AutocompletionRequest.origin especificado.
matched_substrings contiene un conjunto de subcadenas en la descripción que coinciden con los elementos en la entrada del usuario. Esto es útil para resaltar esas substrings en tu aplicación. En muchos casos, la consulta aparece como substring del campo de descripción.
length es la longitud de la substring.
offset es el desplazamiento de caracteres, que se mide desde el principio de la cadena de descripción, donde aparece la subcadena coincidente.
terms es un array que contiene elementos de la búsqueda. En el caso de un lugar, cada elemento representará una parte de la dirección.
offset es el desplazamiento de caracteres, que se mide desde el principio de la cadena de descripción, donde aparece la subcadena coincidente.
value es el término coincidente.
En el siguiente ejemplo, se ejecuta una solicitud de predicción de consulta de la frase "pizza cerca" y se muestra el resultado en una lista.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
const displaySuggestions = function (predictions, status) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
document.getElementById("results").appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
window.initService = initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() puede usar tokens de sesión (si se implementan) para agrupar las solicitudes de autocompletado a los fines de facturación. Los tokens de sesión agrupan las etapas de consulta y selección de la búsqueda con autocompletado de un usuario en una sesión discreta para realizar la facturación correspondiente. La sesión se inicia cuando el usuario comienza a escribir una consulta y termina cuando selecciona un lugar. Cada sesión puede tener varias búsquedas, seguidas de una selección de lugar.
Una vez que finaliza la sesión, el token deja de ser válido. Tu app debe generar un token nuevo para cada sesión. Recomendamos usar tokens de sesión para todas las sesiones de autocompletado. Si se omite el parámetro sessionToken, o si reutilizas un token de sesión, la sesión se cobrará como si no se hubiera proporcionado un token de sesión (cada solicitud se factura por separado).
Puedes usar el mismo token de sesión para realizar una sola solicitud de Place Details en el lugar que se genere a partir de una llamada a AutocompleteService.getPlacePredictions().
En ese caso, la solicitud de autocompletado se combina con la solicitud de Place Details, y la llamada se cobra como una solicitud regular de Place Details. No se aplican cargos por la solicitud de autocompletado.
Asegúrate de pasar un token de sesión único para cada sesión nueva. Si usas el mismo token para más de una sesión de Autocomplete, estas se invalidarán, y todas las solicitudes de Autocomplete que se realicen en las sesiones no válidas se cobrarán de manera individual con el SKU de Autocomplete por solicitud. Obtén más información sobre los tokens de sesión.
En el siguiente ejemplo, se muestra cómo crear un token de sesión y, luego, pasarlo en un AutocompleteService (se omite la función displaySuggestions() para mayor brevedad):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
Asegúrate de pasar un token de sesión único para cada sesión nueva. Usar el mismo token en más de una sesión hará que cada solicitud se facture de forma individual.
Cómo aplicar diseño a los widgets de Autocomplete y SearchBox
Los elementos de la IU proporcionados por Autocomplete y SearchBox traen un diseño predeterminado para incluirse en un mapa de Google Maps. Tal vez sea conveniente ajustar el diseño a tu propio sitio. Las clases de CSS disponibles son las siguientes: Todas las clases que se indican a continuación se aplican a los widgets de Autocomplete y SearchBox.
Clases de CSS para los widgets de Autocomplete y SearchBox
Clase de CSS
Descripción
pac-container
Elemento visual que contiene la lista de predicciones que muestra el servicio de Place Autocomplete. Esta lista aparece como una lista desplegable debajo de los widgets de Autocomplete o SearchBox.
pac-icon
Ícono que aparece a la izquierda de cada elemento de la lista de predicciones.
pac-item
Un elemento de la lista de predicciones que proporcionan los widgets de Autocomplete o SearchBox.
pac-item:hover
La figura que aparece cuando el usuario coloca el cursor sobre un componente.
pac-item-selected
La figura que aparece cuando el usuario selecciona un elemento a través del teclado. Nota: Los elementos seleccionados pertenecerán a esta clase y la clase pac-item.
pac-item-query
Un intervalo dentro de un pac-item que es la parte principal de la predicción. En el caso de las ubicaciones geográficas, contiene un nombre de lugar, como "Sídney", o un nombre y un número de una calle, como "10 King Street". En el caso de las búsquedas basadas en texto, como "pizza en New York", contiene todo el texto de la solicitud. De forma predeterminada, el pac-item-query se muestra de color negro. Si hay texto adicional en pac-item, este queda fuera de pac-item-query y hereda su diseño de pac-item. Su color predeterminado es el gris. El texto adicional normalmente es una dirección.
pac-matched
La parte de la predicción mostrada que coincide con la entrada del usuario. De manera predeterminada, el texto coincidente se resalta en negrita. Ten en cuenta que el texto coincidente puede estar en cualquier parte de pac-item. No necesariamente forma parte de pac-item-query y podría estar parcialmente en pac-item-query y en el texto restante de pac-item.
Cómo utilizar el componente Place Picker
Nota: En este ejemplo, se usa una biblioteca de código abierto. Consulta el archivo readme, en el que se incluyen comentarios sobre esta biblioteca y ayuda para utilizarla.
Prueba los componentes web. Utiliza el componente web Place Picker para permitir la entrada de texto para que los usuarios finales puedan buscar direcciones o lugares específicos con la función de autocompletar.
Figura 1: Entrada de texto para buscar una dirección o lugar específicos con la función de autocompletar
Optimización de Place Autocomplete
En esta sección, se describen algunas prácticas recomendadas que te ayudarán a aprovechar al máximo el servicio Place Autocomplete.
A continuación, se indican algunos lineamientos generales:
Comprende los campos de datos esenciales de Place Autocomplete desde el principio.
Los campos de restricción y personalización de la ubicación son opcionales, pero pueden afectar significativamente el rendimiento del autocompletado.
Usa el procedimiento de manejo de errores para asegurarte de que tu app administre el problema de forma adecuada si la API muestra un error.
Asegúrate de que tu app gestione correctamente los problemas cuando no haya selección y ofrezca a los usuarios una manera de continuar.
Prácticas recomendadas para la optimización de los costos
Optimización básica de los costos
Para optimizar el costo de usar el servicio Place Autocomplete, usa máscaras de campo en los widgets de Place Details y Place Autocomplete, que te permiten mostrar solo los campos de datos de lugar que necesitas.
Optimización avanzada de los costos
Considera utilizar la implementación programática de Place Autocomplete para acceder a los precios por pedido y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details. Los precios por pedido asociados con la API de Geocoding son más rentables que los precios por sesión (basados en sesión) si se cumplen las siguientes condiciones:
Si solo necesitas las coordenadas de latitud y longitud, o la dirección del lugar seleccionado por el usuario, la API de Geocoding proporciona esta información de manera más fácil que una llamada a Place Details.
Si los usuarios seleccionan una predicción de autocompletar con un promedio de cuatro solicitudes o menos, el precio por solicitud puede ser más rentable que el precio por sesión.
Si necesitas ayuda para elegir la implementación de Place Autocomplete más adecuada para tus necesidades, selecciona la pestaña correspondiente a tu respuesta en función de la siguiente pregunta.
¿Tu aplicación requiere algún dato diferente de la dirección y las coordenadas de latitud o longitud de la predicción seleccionada?
Prácticas recomendadas para mejorar el rendimiento
Los siguientes lineamientos describen maneras de optimizar el rendimiento de Place Autocomplete:
Agrega restricciones por país, personalización de la ubicación y, en el caso de las implementaciones programáticas, la preferencia de idioma a la implementación de Place Autocomplete. La preferencia de idioma no es necesaria para los widgets, dado que toman esta información del navegador o el dispositivo móvil del usuario.
Si Place Autocomplete cuenta con un mapa, puedes personalizar la ubicación según su viewport.
En las situaciones en que un usuario no elige una de las predicciones de Autocomplete, generalmente, porque ninguna de ellas indica el resultado deseado, puedes reutilizar la entrada original del usuario para tratar de obtener resultados más relevantes:
Si esperas que el usuario ingrese únicamente información sobre la dirección, vuelve a usar su entrada original en una llamada a la API de Geocoding.
Si esperas que el usuario ingrese búsquedas para un lugar específico por nombre o dirección, usa una solicitud de Find Place.
Si se espera que los resultados pertenezcan únicamente a una región específica, usa la restricción de ubicación.
A continuación, indicamos otras situaciones en las que es mejor recurrir a la API de Geocoding:
Usuarios que ingresan direcciones con números de departamento en países donde la compatibilidad de Place Autocomplete no es completa (p. ej., República Checa, Estonia y Lituania; así, la dirección checa "Stroupežnického 3191/17, Praha" genera una predicción parcial en Place Autocomplete)
Usuarios que ingresan direcciones con prefijos de tramo de ruta, como "23-30 29th St, Queens" en la ciudad de Nueva York o "47-380 Kamehameha Hwy, Kaneohe" en la isla de Kauai en Hawái
