Autocompletar (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Autocomplete (nuevo) muestra predicciones de lugares en respuesta a una solicitud que incluye una cadena de búsqueda de texto y límites geográficos que controlan el área de búsqueda. La función Autocomplete puede buscar coincidencias para palabras completas y subcadenas de la entrada para resolver nombres de lugares, direcciones y Plus Codes. Tu aplicación puede enviar consultas a medida que el usuario escribe para proporcionar predicciones de lugares y consultas sobre la marcha.

Por ejemplo, llamas a Autocomplete con una cadena que contiene una entrada parcial del usuario, "Sicilian piz", con el área de búsqueda limitada a San Francisco, CA. Luego, la respuesta contiene una lista de predicciones de lugares que coinciden con la cadena de búsqueda y el área de búsqueda, como el restaurante llamado "Sicilian Pizza Kitchen".

Las predicciones de lugares que se devuelven están diseñadas para mostrarse al usuario y ayudarlo a seleccionar el lugar deseado. Puedes realizar una solicitud de Place Details (New) para obtener más información sobre cualquiera de las predicciones de lugares que se muestran.

Nota: Autocomplete (nuevo) está disponible en el SDK de Places para Android 3.5.0 y versiones posteriores. Para obtener más información, consulta Elige la versión del SDK. Para obtener más información sobre el uso de las APIs de Kotlin agregadas en la versión 4.0.0, consulta la Descripción general de la referencia.

Solicitudes de Autocomplete (nuevo)

Tu app puede obtener una lista de nombres de lugares o direcciones de predicción a partir de la API de Autocomplete llamando a PlacesClient.findAutocompletePredictions() y pasando un objeto FindAutocompletePredictionsRequest. En el siguiente ejemplo, se muestra una llamada completa a PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Nota: Las llamadas realizadas con widgets de Place Autocomplete siempre llaman a Place Autocomplete, no a Place Autocomplete (nuevo); las llamadas a widgets no se ven afectadas por el método de inicialización.

Nota: Para obtener más información sobre cómo inicializar PlacesClient, consulta Cómo inicializar el cliente de la API de Places.

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza de la mejor manera posible. Una vez que se envíe una solicitud de cancelación, no se mostrará ninguna respuesta. Emitir un token de cancelación NO garantiza que se cancelará una solicitud en particular, y es posible que se te cobre por ella, incluso si no se muestra una respuesta.

Respuestas de Autocomplete (nuevo)

La API muestra un FindAutocompletePredictionsResponse en un Task. FindAutocompletePredictionsResponse contiene una lista de hasta cinco objetos AutocompletePrediction que representan lugares pronosticados. La lista puede estar vacía si no existe ningún sitio conocido que corresponda a la consulta y a los criterios de filtro.

Para cada lugar previsto, puedes llamar a los siguientes métodos para recuperar detalles del lugar:

• getFullText(CharacterStyle) muestra el texto completo de una descripción de lugar. Esta es una combinación del texto primario y secundario. Ejemplo: “Torre Eiffel, Avenida Anatole France, París, Francia”. Además, este método te permite destacar las secciones de la descripción que coincidan con la búsqueda con un estilo que elijas usando CharacterStyle. El parámetro CharacterStyle es opcional. Fijalo en null si no necesitas destacar nada.
• getPrimaryText(CharacterStyle) muestra el texto principal que describe un lugar. Por lo general, es el nombre del lugar. Ejemplos: "Torre Eiffel" y "Calle Pitt 123".
• getSecondaryText(CharacterStyle) muestra el texto secundario de una descripción de lugar. Esto resulta útil, por ejemplo, como segunda línea cuando se muestran las predicciones de autocompletado. Ejemplos: “Avenue Anatole France, París, Francia” y “Sydney, Nueva Gales del Sur”.
• getPlaceId() muestra el ID del lugar de predicción. Un ID de lugar es un identificador textual que identifica de forma exclusiva un lugar y que puedes usar para recuperar el objeto Place nuevamente más tarde. Para obtener más información sobre los IDs de lugar en Autocomplete, consulta Place Details (nuevo). Para obtener información general sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.
• getTypes() muestra la lista de tipos de lugares asociados con este lugar.
• getDistanceMeters() muestra la distancia en línea recta en metros entre este lugar y el origen especificado en la solicitud.

Parámetros obligatorios

• Consulta

  Es la cadena de texto en la que se realiza la búsqueda. Especifica palabras completas y subcadenas, nombres de lugares, direcciones y Plus Codes. El servicio de Autocomplete (nuevo) muestra posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

  Para configurar el parámetro de consulta, llama al método setQuery() cuando compiles el objeto FindAutocompletePredictionsRequest.

Parámetros opcionales

• Tipos principales

  Es una lista de hasta cinco valores de tipo de la Tabla A o la Tabla B que se usan para filtrar los lugares que se muestran en la respuesta. Un lugar debe coincidir con uno de los valores de tipo principal especificados para que se incluya en la respuesta.

  Un lugar solo puede tener un tipo principal de los tipos de la Tabla A o la Tabla B asociados con él. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house".

  La solicitud se rechaza con un error INVALID_REQUEST en los siguientes casos:

  • Se especifican más de cinco tipos.
  • Si se especifican tipos no reconocidos

  Para establecer el parámetro de tipos principales, llama al método setTypesFilter() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Países

  Solo incluye resultados de la lista de países especificados, que se especifica como una lista de hasta 15 valores de ccTLD ("dominio de nivel superior") de dos caracteres. Si se omite, no se aplican restricciones a la respuesta. Por ejemplo, para limitar las regiones a Alemania y Francia, haz lo siguiente:

  Si especificas locationRestriction y includedRegionCodes, los resultados se encuentran en el área de intersección de los dos parámetros de configuración.

  Para establecer el parámetro de países, llama al método setCountries() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Desplazamiento de entrada

  Es el desplazamiento de caracteres Unicode basado en cero que indica la posición del cursor en la consulta. La posición del cursor puede influir en las predicciones que se muestran. Si está vacío, el valor predeterminado es la longitud de la consulta.

  Para establecer el parámetro de offset de entrada, llama al método setInputOffset() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Sesgo de ubicación o restricción de ubicación

  Puedes especificar una preferencia de ubicación o una restricción de ubicación, pero no ambas, para definir el área de búsqueda. Piensa en la restricción de ubicación como la especificación de la región en la que deben estar los resultados y en el sesgo de ubicación como la especificación de la región a la que deben estar cerca los resultados. La diferencia clave es que, con el sesgo de ubicación, es posible que se muestren resultados fuera de la región especificada.

  • Sesgo de ubicación

    Especifica un área para buscar. Esta ubicación funciona como una preferencia, no como una restricción, por lo que es posible que se muestren resultados fuera del área especificada.

    Para establecer el parámetro de sesgo de ubicación, llama al método setLocationBias() cuando compiles el objeto FindAutocompletePredictionsRequest.

  • Restricción de ubicación

    Especifica un área para buscar. No se muestran resultados fuera del área especificada.

    Para establecer el parámetro de restricción de ubicación, llama al método setLocationRestriction() cuando compiles el objeto FindAutocompletePredictionsRequest.

  Especifica el sesgo de ubicación o la región de restricción de ubicación como un viewport rectangular o un círculo.

  • Un círculo se define por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. El valor predeterminado es 0.0. Para la restricción de ubicación, debes establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud no muestra resultados.

  • Un rectángulo es un viewport de latitud y longitud, representado como dos puntos low y high diagonalmente opuestos. Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben oscilar entre -90 y 90 grados inclusive, y los límites de longitud deben oscilar entre -180 y 180 grados inclusive:

    Nota: Los tipos de sesgo admitidos varían según la versión del SDK que uses. CircularBounds solo está disponible en Autocomplete (nuevo).
    • Si low = high, la ventana de visualización consta de ese único punto.
    • Si low.longitude > high.longitude, el rango de longitud se invierte (la ventana de visualización cruza la línea de longitud de 180 grados).
    • Si low.longitude = -180 grados y high.longitude = 180 grados, la ventana de visualización incluye todas las longitudes.
    • Si low.longitude = 180 grados y high.longitude = -180 grados, el rango de longitud está vacío.

    Se deben propagar low y high, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

• Origen

  Es el punto de origen desde el que se calcula la distancia en línea recta hasta el destino (al que se accede con getDistanceMeters()). Si se omite este valor, no se mostrará la distancia en línea recta. Se deben especificar como coordenadas de latitud y longitud:

  Para establecer el parámetro de origen, llama al método setOrigin() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Código de la región

  Es el código de región que se usa para dar formato a la respuesta, incluido el formato de la dirección, especificado como un valor de dos caracteres de ccTLD ("dominio de nivel superior"). La mayoría de los códigos ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad de "Reino Unido de Gran Bretaña e Irlanda del Norte").

  Nota: El código de región está destinado a representar la región de la que se origina la solicitud, no necesariamente la región de segmentación de la consulta.

  Si especificas un código de región no válido, la API mostrará un error INVALID_ARGUMENT. El parámetro puede afectar los resultados según la ley aplicable.

  Para establecer el parámetro de código de región, llama al método setRegionCode() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Token de sesión

  Los tokens de sesión son cadenas generadas por el usuario que hacen un seguimiento de las llamadas a Autocomplete (nuevo) como "sesiones". Autocomplete usa tokens de sesión para agrupar 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 comienza 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 una sesión, el token deja de ser válido. Tu app debe generar un token nuevo para cada sesión. Te recomendamos que uses tokens de sesión para todas las sesiones de autocompletado programático (cuando incorporas un fragmento o inicias el autocompletado con un intent, la API se encarga de esto automáticamente).

  El Autocomplete usa un AutocompleteSessionToken para identificar cada sesión. Tu app debe pasar un token de sesión nuevo cuando se inicia cada sesión nueva y, luego, pasar ese mismo token, junto con un ID de lugar, en la llamada posterior a fetchPlace() para recuperar los detalles del lugar que seleccionó el usuario.

  Para establecer el parámetro de token de sesión, llama al método setSessionToken() cuando compiles el objeto FindAutocompletePredictionsRequest.

  Para obtener más información, consulta Tokens de sesión.

Ejemplos de Autocomplete (nuevo)

Usa la restricción de ubicación y el sesgo de ubicación

Autocomplete (nuevo) usa la polarización de IP de forma predeterminada para controlar el área de búsqueda. Con el sesgo de IP, la API usa la dirección IP del dispositivo para sesgar los resultados. De manera opcional, puedes usar la restricción de ubicación o el sesgo de ubicación, pero no ambos, para especificar un área en la que buscar.

La restricción de ubicación especifica el área en la que se realizará la búsqueda. No se muestran resultados fuera del área especificada. En el siguiente ejemplo, se usa la restricción de ubicación para limitar la solicitud a una restricción de ubicación circular con un radio de 5,000 metros centrado en San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Con el sesgo de ubicación, la ubicación funciona como un sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera del área especificada. En el siguiente ejemplo, se cambia la solicitud anterior para usar el sesgo de ubicación:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Usa tipos principales

Usa el parámetro primary types para restringir los resultados de una solicitud a un tipo determinado, como se indica en la Tabla A y la Tabla B. Puedes especificar un array de hasta cinco valores. Si se omite, se muestran todos los tipos.

En el siguiente ejemplo, se especifica una cadena de consulta de "Fútbol" y se usa el parámetro de tipos principales para restringir los resultados a establecimientos de tipo "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Si omites el parámetro de tipos principales, los resultados pueden incluir establecimientos de un tipo que no deseas, como "athletic_field".

Cómo usar el origen

Cuando incluyes el parámetro origin en la solicitud, especificado como coordenadas de latitud y longitud, la API incluye la distancia en línea recta del origen al destino en la respuesta (a la que se accede con getDistanceMeters()). En este ejemplo, se establece el origen en el centro de San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Atribuciones

Puedes usar Autocomplete (nuevo) incluso sin un mapa. Si muestras un mapa, debe ser de Google. Cuando muestras predicciones del servicio de Autocomplete (nuevo) sin un mapa, debes incluir el logotipo de Google intercalado con el campo de búsqueda o los resultados. Para obtener más información, consulta Cómo mostrar el logotipo y las atribuciones de Google.