Place Autocomplete

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.
Seleccionar plataforma: Android iOS JavaScript Servicio web

Introducción

El autocompletado es una función de la biblioteca de Places de la API de Maps JavaScript. Puedes usar el autocompletado para que tus aplicaciones tengan un comportamiento de escritura anticipada en el campo de búsqueda de Google Maps. El servicio de autocompletado puede coincidir con palabras completas y substrings, lo que resuelve los nombres de lugares, las direcciones y los códigos de suma. Por lo tanto, las aplicaciones pueden enviar consultas a medida que el usuario escribe para proporcionar predicciones de sitios sobre la marcha.

Cómo comenzar

Antes de usar la biblioteca de Places en la API de Maps JavaScript, asegúrate de que la API de Places 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:

  1. Ve a la consola de Google Cloud.
  2. 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.
  3. En la lista de APIs del Panel, busca API de Places.
  4. Si ves la API en la lista, no necesitas hacer nada más. Si la API no figura en la lista, debes habilitarla:
    1. 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.
    2. Busca la opción API de Places y selecciónala en la lista de resultados.
    3. 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&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 el campo para detectar entradas de caracteres. 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, la información sobre el lugar se devuelve al objeto de autocompletado y tu aplicación puede recuperarla. Consulta los detalles a continuación.
    Un campo de texto de autocompletado y la lista de selección de predicciones de sitios proporcionadas a medida que el usuario ingresa la búsqueda.
    Figura 1: Campo de autocompletado de texto y lista de selección
    Formulario de dirección completo.
    Figura 2: Formulario de dirección completo
  • SearchBox agrega un campo de entrada de texto a tu página web, de manera muy similar a Autocomplete. Las diferencias son las siguientes:
    • 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 sitios (según lo definido en la API de Places) y términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza" en "new" (nueva), la lista de selección puede incluir la frase "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, puedes restringir la búsqueda en función de un LatLngBounds determinado. En este último, puedes restringir la búsqueda a un país y un tipo de lugar en particular, así como configurar los límites. Para obtener más información, consulta a continuación.
    Formulario de dirección completo.
    Figura 3: Un cuadro de búsqueda presenta términos de búsqueda y predicciones de lugares.
    Consulta los detalles a continuación.
  • Puedes crear un objeto AutocompleteService para recuperar predicciones de manera programática. Llama a getPlacePredictions() para recuperar los lugares que coinciden o llama a getQueryPredictions() para recuperar los lugares coincidentes y los términos de búsqueda sugeridos. Nota: AutocompleteService no agrega controles de IU. En lugar de ello, los métodos anteriores devuelven un arreglo 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 cómo el resultado coincide con la entrada del usuario. Consulta los detalles a continuación.

Cómo agregar un widget de Autocomplete

El widget Autocomplete crea un campo de entrada de texto en tu página web, proporciona predicciones de lugares en una lista de selección de IU y muestra detalles del lugar en respuesta a una solicitud getPlace(). Cada entrada de la lista de selección corresponde a un solo lugar (según lo define la API de Places).

El constructor Autocomplete toma dos argumentos:

  • Un elemento HTML input de tipo text. Este es el campo de entrada que el servicio de autocompletado supervisará y adjuntará sus resultados.
  • Un argumento AutocompleteOptions opcional, que puede contener las siguientes propiedades:
    • Un arreglo de datos fields que se incluirá en la respuesta Place Details del 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 arreglo 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 los tipos.
    • bounds es un objeto google.maps.LatLngBounds que especifica el área en la que se buscarán lugares. Los resultados se inclinan hacia, pero no se limitan a, los lugares contenidos dentro de estos límites.
    • strictBounds es un boolean que especifica si la API debe mostrar solo los sitios que están estrictamente dentro de la región definida por el bounds especificado. La API no muestra resultados fuera de esta región, incluso si coinciden con la entrada del usuario.
    • componentRestrictions se puede usar para restringir los resultados a grupos específicos. Actualmente, puedes usar componentRestrictions para filtrar por hasta 5 países. Los países se deben ingresar como un código de país de dos caracteres, ISO 3166-1 alfa-2 compatible. Se deben pasar varios países como una lista de códigos de país.

      Nota: Si recibes resultados inesperados con un código de país, verifica que estés usando un código que 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 ID de lugar. Cuando llamas 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 mostrado con llamadas a los servicios de sitios, geocodificación, indicaciones o matriz de distancia.

Cómo restringir las predicciones de Autocomplete

De manera predeterminada, Place Autocomplete presenta todos los tipos de sitios, restringidos para predicciones cerca de la ubicación del usuario y obtiene todos los campos de datos disponibles para el lugar seleccionado del usuario. Configura las opciones de Place Autocomplete para presentar predicciones más relevantes según tu caso práctico.

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 sitios de tipo establishment, los que se priorizan dentro del área geográfica especificada y la restricción de predicciones solo a lugares dentro de Estados Unidos. Si estableces la opción fields, se especifica la información que se mostrará sobre el lugar seleccionado por el usuario.

Llama a setOptions() para cambiar el valor de una opción de 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Especifica campos de datos

Especifica los campos de datos para evitar que se te facture por los SKU de datos de lugares que no necesitas. Incluye la propiedad fields en el AutocompleteOptions que se pasa 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"]);

Define sesgos y límites de área de búsqueda para autocompletar

Puedes restringir los resultados de autocompletado para priorizar una ubicación o área aproximada de las siguientes maneras:

  • Establece los límites en la creación del objeto Autocomplete.
  • Cambia los límites en un Autocomplete existente.
  • Establece los límites en el viewport del mapa.
  • Restringe la búsqueda a los límites.
  • Restringir la búsqueda a un país específico.

En el ejemplo anterior, se muestra la configuración de límites en la creación. Los siguientes ejemplos demuestran las otras 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 restringir los resultados a la vista del puerto del mapa, incluso mientras esa ventana gráfica cambia.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Usa unbind() para desvincular las predicciones de Autocompletar 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 });

Ver ejemplo

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"],
});

Ver ejemplo

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 una colección de tipos, como se indica en Tipos de lugares. Si no se especifica 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 arreglo que contiene hasta cinco valores de la Tabla 1 o la Tabla 2 de los Tipos de lugar. Por ejemplo:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    o:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Cualquier filtro de la tabla 3 de Tipos de lugar Solo puedes especificar un valor único en la tabla 3.

La solicitud se rechazará en los siguientes casos:

  • Especifica más de cinco tipos.
  • Especifica cualquier tipo no reconocido.
  • Puedes combinar cualquier tipo de la Tabla 1 o la Tabla 2 con cualquier filtro de la Tabla 3.

La demostración de Places Autocomplete demuestra las diferencias en las predicciones entre diferentes tipos de sitios.

Visitar demostración

Cómo obtener información del lugar

Cuando un usuario selecciona un lugar de las predicciones adjuntas al campo de texto de autocompletado, el servicio activa un evento place_changed. Para obtener detalles del lugar, haz lo siguiente:

  1. Crea un controlador de eventos para el evento place_changed y llama a addListener() en el objeto Autocomplete a fin de agregar el controlador.
  2. Llama a Autocomplete.getPlace() en el objeto Autocomplete para recuperar un objeto PlaceResult, que puedes usar para obtener más información sobre el lugar seleccionado.

De manera predeterminada, cuando un usuario selecciona un lugar, el autocompletado devuelve todos los campos de datos disponibles para el lugar seleccionado, y se te facturará según corresponda. Usa Autocomplete.setFields() para especificar qué campos de datos de lugar se mostrarán. Obtén más información sobre el objeto PlaceResult, incluida una lista de campos de datos de lugar que puedes solicitar. Para evitar pagar por datos que no necesitas, asegúrate de usar Autocomplete.setFields() a fin de especificar solo los datos de lugar que usarás.

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 del 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 en 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;

Ver ejemplo

Cómo personalizar el texto del marcador de posición

De forma predeterminada, el campo de texto creado por el servicio de autocompletado contiene texto de marcador de posición estándar. 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 del marcador de posición predeterminado se localiza automáticamente. Si especificas tu propio valor de marcador de posición, debes administrar la localización de ese valor en tu aplicación. Para obtener información sobre cómo la API de Google Maps JavaScript selecciona el idioma que se usará, lee la documentación sobre la localización.

Consulta Cómo definir el estilo de los widgets de Autocomplete y SearchBox para personalizar la apariencia del widget.

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 se ingresa texto, el servicio muestra predicciones en forma de lista desplegable.

SearchBox proporciona una lista extendida de predicciones, que pueden incluir lugares (según lo define la API de Places) y términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza" en "new" (pizza en nueva), la lista de selección puede incluir la frase "pizza" en Nueva York, NY y los nombres de varias tiendas de pizza. Cuando un usuario selecciona un lugar de la lista, la información sobre ese lugar se devuelve al objeto SearchBox y tu aplicación puede recuperarla.

El constructor SearchBox toma dos argumentos:

  • Un elemento HTML input de tipo text. Este es el campo de entrada que el servicio SearchBox supervisará y al que adjuntará 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 inclinan hacia, pero no se limitan a, los lugares contenidos dentro de estos límites.

El siguiente código usa el parámetro de límites para restringir los resultados hacia lugares dentro de un área geográfica en particular, especificado 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.

Ver ejemplo

Cómo obtener información del lugar

Cuando el usuario selecciona un elemento de las predicciones adjuntas al cuadro de búsqueda, el servicio activa un evento places_changed. Puedes llamar a getPlaces() en el objeto SearchBox para recuperar un arreglo que contiene varias 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 los detalles de los lugares.

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

Ver ejemplo

Consulta Cómo definir el estilo de los widgets de Autocomplete y SearchBox para personalizar la apariencia del widget.

Cómo recuperar de forma programática las predicciones del servicio Place Autocomplete

Para recuperar predicciones de manera programática, usa la clase AutocompleteService. AutocompleteService no agrega ningún control de la IU. En su lugar, muestra un arreglo de objetos de predicción, cada uno con el texto de la predicción, información de referencia y detalles de cómo el resultado coincide con la entrada del usuario. Esto es útil si deseas tener más control sobre la interfaz de usuario que el que ofrecen Autocomplete y SearchBox descritos anteriormente.

AutocompleteService expone los siguientes métodos:

  • getPlacePredictions() muestra predicciones del lugar. Nota: Un &place3 puede ser un establecimiento, una ubicación geográfica o un punto de interés destacado, según lo define la API de Places.
  • getQueryPredictions() muestra una lista extendida de predicciones, que puede incluir sitios (según lo definido en la API de Places) y términos de búsqueda sugeridos. Por ejemplo, si el usuario escribe "pizza" en "new" (pizza en nueva), la lista de selección puede incluir la frase "pizza" en Nueva York, NY y los nombres de varias pizzerías.

Ambos métodos muestran un arreglo de objetos de predicción con la siguiente forma:

  • description es la predicción coincidente.
  • distance_meters es la distancia en metros del lugar desde el AutocompletionRequest.origin especificado.
  • matched_substrings contiene un conjunto de substrings en la descripción que coinciden con elementos en la entrada del usuario. Esto es útil para destacar esas substrings en tu aplicación. En muchos casos, la consulta aparecerá como una substring del campo de descripción.
    • length es la longitud de la substring.
    • offset es el desplazamiento de caracteres, medido desde el principio de la string de descripción, en el que aparece la substring coincidente.
  • place_id es un identificador textual que identifica de forma exclusiva un lugar. Para recuperar información sobre el lugar, pasa este identificador en el campo placeId de una solicitud a Place Details. Obtén más información sobre cómo hacer referencia a un lugar con un ID de lugar.
  • terms es un arreglo que contiene elementos de la consulta. Por lo general, para un sitio, cada elemento constituirá una parte de la dirección.
    • offset es el desplazamiento de caracteres, medido desde el principio de la string de descripción, en el que aparece la substring coincidente.
    • value es el término coincidente.

En el siguiente ejemplo, se ejecuta una solicitud de predicción de consulta para 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Prueba la muestra

Ver ejemplo

Tokens de sesión

AutocompleteService.getPlacePredictions() usa tokens de sesión para agrupar solicitudes de autocompletado con fines de facturación. Los tokens de sesión agrupan las fases de consulta y selección de la búsqueda de autocompletado de un usuario en una sesión discreta con fines de facturación. La sesión comienza cuando el usuario comienza a escribir una consulta y termina cuando selecciona un lugar. Cada sesión puede tener varias consultas, seguidas de una selección de lugar. Una vez que finaliza una 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 vuelves a usar 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 resulta de una llamada a AutocompleteService.getPlacePredictions(). En este caso, la solicitud de autocompletado se combina con la solicitud de Place Details y la llamada se cobra como una solicitud normal 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, se invalidarán esas sesiones, 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 abreviar):

// 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. Si usas el mismo token en más de una sesión, cada solicitud se factura 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

De forma predeterminada, los elementos de la IU proporcionados por Autocomplete y SearchBox tienen un estilo que permite su inclusión en un mapa de Google. Es posible que desees ajustar el estilo para que se adapte a tu sitio. Están disponibles las siguientes clases de CSS. Todas las clases que se indican a continuación se aplican a los widgets Autocomplete y SearchBox.

Una ilustración gráfica de las clases de CSS para los widgets de Autocomplete y SearchBox
Clases de CSS para los widgets de Autocomplete y SearchBox
Clase de CSS Descripción
pac-container El elemento visual que contiene la lista de predicciones que muestra el servicio de Place Autocomplete. Esta lista aparece como una lista desplegable debajo del widget Autocomplete o SearchBox.
pac-icon El ícono que se muestra a la izquierda de cada elemento en la lista de predicciones.
pac-item Un elemento de la lista de predicciones que proporcionan el widget Autocomplete o SearchBox.
pac-item:hover La figura que aparece cuando el usuario posa el puntero del mouse sobre un elemento.
pac-item-selected La figura que aparece cuando el usuario selecciona un elemento a través del teclado. Nota: Los elementos seleccionados serán miembros de esta clase y de la clase pac-item.
pac-item-query Un intervalo dentro de un pac-item que es la parte principal de la predicción. Para ubicaciones geográficas, contiene el nombre de un lugar, como "Sídney" o el nombre y el número de una calle, como '10 King Street'. Para las búsquedas basadas en texto, como &pizza en Nueva York, contiene el texto completo de la consulta. De forma predeterminada, el pac-item-query es de color negro. Si hay texto adicional en pac-item, está fuera de pac-item-query y hereda su estilo de pac-item. Su color predeterminado es el gris. Por lo general, el texto adicional es una dirección.
pac-matched Parte de la predicción devuelta que coincide con la entrada del usuario. De forma predeterminada, este texto coincidente se destaca en negrita. Ten en cuenta que el texto coincidente puede estar en cualquier lugar dentro de pac-item. No es necesariamente parte de pac-item-query y podría estar en parte dentro de pac-item-query y en parte en el texto restante en pac-item.

Optimización de Place Autocomplete

En esta sección, se describen las prácticas recomendadas para ayudarte a aprovechar al máximo el servicio de Place Autocomplete.

Estos son algunos lineamientos generales:

  • La forma más rápida de desarrollar una interfaz de usuario que funcione es usar el widget Autocomplete de la API de Maps JavaScript, el widget de autocompletado del SDK de Places para Android o el control de IU de autocompletado del SDK de Places para iOS
  • Comprende los campos de datos esenciales de Place Autocomplete desde el principio.
  • Los campos de restricción de ubicación y restricción de ubicación son opcionales, pero pueden afectar de forma significativa el rendimiento del autocompletado.
  • Usa el manejo de errores para asegurarte de que tu app se degrade con elegancia si la API muestra un error.
  • Asegúrate de que tu app la maneje 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 de Place Autocomplete, usa máscaras de campo en los widgets de Place Details y Place Autocomplete a fin de mostrar solo los campos de datos de lugar que necesites.

Optimización avanzada de los costos

Considera la implementación programática de Place Autocomplete para acceder a precios por solicitud y solicitar resultados de la API de Geocoding sobre el sitio seleccionado en lugar de Place Details. El precio por solicitud combinado con la API de Geocoding es más rentable que el precio por sesión (basado en sesión) si se cumplen las siguientes condiciones:

  • Si solo necesitas la latitud y longitud o la dirección del sitio seleccionado por el usuario, la Geocoding API proporciona esta información para una llamada a Place Details.
  • Si los usuarios seleccionan una predicción de autocompletado en un promedio de cuatro solicitudes de predicción de autocompletado 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 que mejor se adapte a tus necesidades, selecciona la pestaña correspondiente a tu respuesta a la siguiente pregunta.

¿Tu aplicación requiere información que no sea la dirección y latitud o longitud de la predicción seleccionada?

Sí, necesita más detalles.

Usa Place Autocomplete basado en sesiones con Place Details.
Debido a que tu aplicación requiere 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 (de manera programática o incorporado en los widgets de JavaScript, Android o iOS) por un costo total de USD 0.017 por sesión, además de los SKU de Places Data aplicables.5

Implementación de widgets
La administración de sesiones se incorpora 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 garantizar que solo solicites los campos de datos de lugar que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes a Place Autocomplete. Cuando solicites Place Details sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El id. de sitio de la respuesta de autocompletado de sitios.
  2. El token de sesión que se usó en la solicitud a Place Autocomplete
  3. 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 del uso de Place Autocomplete. La eficiencia del autocompletado de cada aplicación varía según lo que ingresen los usuarios, dónde se use la aplicación y si se implementaron 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 en cuatro o menos solicitudes?

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 $0.005 por solicitud. Realizar cuatro solicitudes de Place Autocomplete, por solicitud cuesta $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 $0.01632, que es menor que el precio por autocompletado de sesión de $0.017 por sesión.1

Considera usar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

No

Usa 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 de los precios por sesión, tu implementación de Place Autocomplete debe usar un token de sesión para las solicitudes a Place Autocomplete y la solicitud a Place Details asociada, con un costo total de $0.017 por sesión.1

Implementación de widgets
La administración de sesiones se incorpora 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 que solo solicites campos de datos básicos.

Implementación programática
Usa un token de sesión con tus solicitudes a Place Autocomplete. Cuando solicites Place Details sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El id. de sitio de la respuesta de autocompletado de sitios.
  2. El token de sesión que se usó en la solicitud a Place Autocomplete
  3. El parámetro fields especifica campos de datos básicos, como la dirección y 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, realizar solicitudes de Place Autocomplete para cada carácter después de que el usuario haya escrito el tercer carácter significa que, si el usuario escribe siete caracteres, selecciona una predicción para la que realizarás una solicitud a la API de Geocoding, el costo total sería $0.01632 (4 * $0.00283 Autocomplete por solicitud + $0.005 Geocoding).1

Si las solicitudes retrasadas pueden hacer que tu solicitud programática sea inferior a cuatro, puedes seguir la guía para la implementación del autocompletado de sitios con la API de Geocoding. Ten en cuenta que el usuario que podría esperar ver las predicciones con cada pulsación de tecla nueva puede percibir la demora en las solicitudes.

Considera usar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan en menos caracteres.


  1. Los costos que se indican aquí son en USD. Consulta la página Facturación de Google Maps Platform para obtener información completa sobre los precios.

Prácticas recomendadas para el rendimiento

Las siguientes pautas describen las maneras de optimizar el rendimiento del autocompletado de sitios:

  • Agrega restricciones de país, restricción de ubicación y preferencia de idioma (para implementaciones programáticas) a tu implementación de Place Autocomplete. Con los widgets, no se necesita una preferencia de idioma, ya que se eligen en el navegador o en el dispositivo móvil del usuario.
  • Si el autocompletado de sitios está acompañado de un mapa, puedes restringir la ubicación según el viewport del mapa.
  • Si un usuario no selecciona una de las predicciones de Autocompletar, por lo general, debido a que ninguna de esas predicciones es la dirección de resultado deseada, puedes volver a usar la entrada original del usuario para intentar obtener resultados más relevantes:
    • Si esperas que el usuario ingrese solo información de dirección, vuelve a usar la entrada original del usuario en una llamada a la API de Geocoding.
    • Si esperas que el usuario ingrese consultas para un lugar específico por nombre o dirección, usa una solicitud de Place Place. Si los resultados solo se esperan en una región específica, usa la restricción de ubicación.
    Otros casos en los que es mejor recurrir a la API de Geocoding son los siguientes:
    • Usuarios que ingresan direcciones locales en países distintos de Australia, Canadá o Nueva Zelanda Por ejemplo, la dirección estadounidense 123 Bowdoin St #456, Boston MA, EE.UU. no es compatible con el autocompletado. (Autocompletar admite direcciones locales únicamente en Australia, Canadá y Nueva Zelanda). Los formatos de dirección admitidos en estos tres países son "9/321 Pitt Street, Sídney, Nueva Gales del Sur, Australia", o "14/19 Langana Avenue, Browns Bay, Auckland, Nueva Zelanda" o "145-112 Renfrew Dr, Markham, Ontario, Canadá").
    • Los usuarios que ingresan direcciones con prefijos de tramo de ruta como "23-30 29th St, Queens" en Nueva York o "47-380 Kamehameha Hwy, Kaneohe" en la isla de Kauai en Hawai.

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.