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:
- Ve a la consola de Google Cloud.
- 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:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Consulta la Descripción general de bibliotecas para obtener más información.
Resumen de clases
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ón Imagen 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 conAutocomplete
. 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 queAutocomplete
para restringir la búsqueda. En el primero, es posible personalizar la búsqueda en función de un objetoLatLngBounds
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. - La diferencia principal radica en los resultados que aparecen en la lista de selección.
- Puedes crear un objeto
AutocompleteService
para obtener predicciones de manera programática. Llama agetPlacePredictions()
para obtener los lugares coincidentes, o bien agetQueryPredictions()
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 tipotext
: 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 respuestaPlace Details
para elPlaceResult
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, consultaPlaceResult
- 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 objetogoogle.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ímitesstrictBounds
es unboolean
que especifica si la API debe mostrar solo los lugares que están estrictamente dentro de la región definida por elbounds
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 utilizarcomponentRestrictions
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ísNota: 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 widgetAutocomplete
que recupere solo los IDs de lugar. Cuando llames agetPlace()
en el objetoAutocomplete
, elPlaceResult
disponible solo tendrá configuradas las propiedadesplace id
,types
yname
. Puedes usar el ID de lugar que se muestra con las llamadas a los servicios Places, Geocoding, Directions o Distance Matrix
- Un array de datos
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);
JavaScript
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"); 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 campos de datos
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.
autocomplete.setFields(["place_id", "geometry", "name"]);
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.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Configura los límites del viewport del mapa
Usa bindTo()
para personalizar los resultados en función del viewport del mapa, incluso mientras ese viewport cambia.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Usa unbind()
para desvincular las predicciones de Autocomplete del viewport del mapa.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Restringe la búsqueda a los límites actuales
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.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Limita los tipos de lugares
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:
Un array con hasta cinco valores de la Tabla 1 o la Tabla 2 de los Tipos de lugar Por ejemplo:
types: ['hospital', 'pharmacy', 'bakery', 'country']
O bien:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Cualquier filtro de la Tabla 3 de Tipos de lugar; solo puedes especificar un valor de la Tabla 3.
La solicitud se rechazará en los siguientes casos:
- Si especificas más de cinco tipos
- Si especificas algún tipo no reconocido
- Si combinas cualquier tipo de la Tabla 1 o la Tabla 2 con cualquier filtro de la Tabla 3
La demostración de Place Autocomplete expone las diferencias entre las predicciones de los distintos tipos de lugares.
Cómo obtener información del lugar
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 aaddListener()
en el objetoAutocomplete
para agregarlo al controlador. - Llama a
Autocomplete.getPlace()
en el objetoAutocomplete
para obtener un objetoPlaceResult
, 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(); }
JavaScript
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.
Consulta Cómo aplicar diseño a los widgets de Autocomplete y SearchBox para personalizar su apariencia.
Cómo agregar un widget de SearchBox
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 tipotext
: El servicio deSearchBox
controla este campo de entrada y le adjunta sus resultados. - Un argumento
options
, que puede contener la propiedadbounds
:bounds
es un objetogoogle.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.
Cómo obtener información del lugar
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); });
JavaScript
// 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); });
Consulta Cómo aplicar diseño a los widgets de Autocomplete y SearchBox para personalizar su apariencia.
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.
Ambos métodos muestran un array de objetos de predicción con la siguiente forma:
description
es la predicción coincidente.distance_meters
es la distancia en metros entre lugar y elAutocompletionRequest.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.
place_id
es un identificador textual que identifica un lugar de forma exclusiva. Para obtener información sobre el lugar, pasa este identificador en el campoplaceId
de una solicitud de Place Details. Obtén más información sobre cómo hacer referencia a un lugar con un ID de lugar.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;
JavaScript
// 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;
CSS
HTML
<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>
Prueba la muestra
Tokens de sesión
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.
Obtén más información sobre los tokens de sesión.
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
.
![Ilustración de las clases de CSS para los widgets de Autocomplete y SearchBox](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?authuser=3&hl=es-419)
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.
![GIF con cuadro de búsqueda. El usuario comienza a ingresar una dirección como entrada y aparece un menú desplegable con direcciones relacionadas. El usuario hace clic en una dirección de este menú y el cuadro de búsqueda se completa con el resto de la dirección.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-picker.gif?authuser=3&hl=es-419)
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:
- La forma más rápida de desarrollar una interfaz de usuario funcional es usar el widget de Autocomplete de la API de Maps JavaScript, el widget de Autocomplete del SDK de Places para Android o el control de la IU de Autocomplete del SDK de Places para iOS.
- 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.
¿Tu aplicación requiere algún dato diferente de la dirección y las coordenadas de latitud o longitud de la predicción seleccionada?
Sí, necesita más detalles.
Usa el servicio Place Autocomplete basado en sesiones con Place Details.
Dado que tu aplicación requiere datos de Place Details, como el nombre del lugar, el estado de la empresa o el horario de atención, tu implementación de Place Autocomplete debe usar un token de sesión (programático o integrado en los widgets de JavaScript, Android o iOS) por un costo total de USD 0.017 por sesión más los SKUs de datos de Places aplicables según los campos de datos de lugar que solicites.1
Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android o iOS. Esto incluye las solicitudes de Place Autocomplete y Place Details en la predicción seleccionada. Asegúrate de especificar el parámetro fields
para asegurarte de solicitar únicamente los campos de datos de lugar que necesitas.
Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete. Cuando solicites la predicción seleccionada a Place Details, incluye los siguientes parámetros:
- El ID de lugar de la respuesta de Place Autocomplete
- El token de sesión que se utilizó en la solicitud de Place Autocomplete
- El parámetro
fields
que especifica los campos de datos de lugar que necesitas
No, solo requiere la dirección y la ubicación.
La API de Geocoding podría ser una opción más rentable que Place Details para tu aplicación, según el rendimiento de su uso de Place Autocomplete. La eficiencia de Autocomplete de cada aplicación varía según las búsquedas que ingresan los usuarios, dónde se usa la aplicación y si se siguen las prácticas recomendadas de optimización del rendimiento.
Para responder la siguiente pregunta, analiza cuántos caracteres escribe un usuario en promedio antes de seleccionar una predicción de Place Autocomplete en tu aplicación.
¿Tus usuarios seleccionan, en promedio, una predicción de Place Autocomplete cada cuatro solicitudes o menos?
Sí
Implementa Place Autocomplete de manera programática sin tokens de sesión y llama a la API de Geocoding en la predicción de lugar seleccionada.
La API de Geocoding proporciona direcciones y coordenadas de latitud y longitud por USD 0.005 por solicitud. Realizar cuatro solicitudes de Place Autocomplete por solicitud cuesta USD 0.01132, por lo que el costo total de cuatro solicitudes más una llamada a la API de Geocoding sobre la predicción de lugar seleccionada sería de USD 0.01632, lo cual es inferior al precio del autocompletado por sesión, que es de USD 0.017.1
Considera aplicar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.
No
Usa el servicio Place Autocomplete basado en sesiones con Place Details.
Dado que la cantidad promedio de solicitudes que esperas hacer antes de que un usuario seleccione una predicción de Place Autocomplete supera el costo del precio por sesión, la implementación de Place Autocomplete debe usar un token de sesión para las solicitudes de Place Autocomplete y la solicitud de Place Details asociada por un costo total de USD 0.017 por sesión.1
Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android o iOS. Esto incluye las solicitudes de Place Autocomplete y Place Details en la predicción seleccionada. Asegúrate de especificar el parámetro fields
para asegurarte de solicitar únicamente campos de datos básicos.
Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete. Cuando solicites la predicción seleccionada a Place Details, incluye los siguientes parámetros:
- El ID de lugar de la respuesta de Place Autocomplete
- El token de sesión que se utilizó en la solicitud de Place Autocomplete
- El parámetro
fields
que especifica campos de datos básicos, como la dirección y la geometría
Considera retrasar las solicitudes de Place Autocomplete
Puedes emplear estrategias como demorar una solicitud de Place Autocomplete hasta que el usuario escriba los primeros tres o cuatro caracteres para que tu aplicación realice menos solicitudes. Por ejemplo, cuando se realizan solicitudes de Place Autocomplete para cada carácter después de que el usuario escribe el tercer carácter, si el usuario escribe siete caracteres y luego selecciona una predicción para la cual haces una solicitud a la API de Geocoding, el costo total será de USD 0.01632 (4 * USD 0.00283 (autocompletado por solicitud) + USD 0.005 (Geocoding)).1
Si retrasar las solicitudes puede hacer que tu solicitud programática promedio sea inferior a cuatro, puedes seguir las instrucciones para implementar Place Autocomplete con la API de Geocoding y obtener un rendimiento optimizado. Ten en cuenta que demorar las solicitudes puede percibirse como latencia por parte del usuario, que tal vez espere ver predicciones con cada letra que ingresa.
Considera seguir las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.
-
Los costos se indican en USD. Consulta la página Facturación de Google Maps Platform para obtener información completa sobre los precios.
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.
- 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
Límites y políticas de uso
Cuotas
Para obtener información sobre las cuotas y los precios, consulta la documentación de uso y facturación de la API de Places.
Políticas
El uso de la biblioteca de Places para la API de Maps JavaScript debe cumplir con las políticas que se describen para la API de Places.