Place Autocomplete

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:

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 está en la lista, habilítala:
   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&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.

  

  

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

  

  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.

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);
index.ts

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);
index.js

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.

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);
index.ts

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);
index.js

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.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Usa unbind() para desvincular las predicciones de Autocomplete del viewport del mapa.

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.ts

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

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.

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

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

Ver demostración

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:

1. Crea un controlador para el evento place_changed y llama a addListener() en el objeto Autocomplete para agregarlo al controlador.
2. 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.

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();
}
index.ts

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;
index.js

Ver ejemplo

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

Ver ejemplo

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.

// 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);
});
index.ts

// 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);
});
index.js

Ver ejemplo

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 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.
• 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 campo placeId 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.

// 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;
index.ts

// 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;
index.js

style.css

<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>
index.html

Ver ejemplo

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.

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?

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 la dirección del 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 de subpremios, como direcciones de unidades o departamentos específicos dentro de un edificio 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.