Autocompletar (nuevo)

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 en el momento.

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

Las predicciones de lugares que se muestran están diseñadas para presentarse al usuario con el fin de ayudarlo a seleccionar el lugar deseado. Puedes realizar una solicitud a Place Details (nuevo) para obtener más información sobre cualquiera de las predicciones de lugar 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 Cómo elegir tu versión del SDK.

Solicitudes a Autocomplete (nuevo)

Tu app puede obtener una lista de nombres de lugares o direcciones previstos de la API de autocompletado 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 que se realizan con los 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.

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza sobre la base del mejor esfuerzo. Una vez que se envía 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 la solicitud incluso si no se muestra una respuesta.

Respuestas de Autocomplete (nuevo)

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

Para cada lugar de predicción, puedes llamar a los siguientes métodos a fin de recuperar detalles relacionados:

• getFullText(CharacterStyle) muestra el texto completo de la descripción de un lugar. Esta es una combinación del texto principal y secundario. Ejemplo: “Torre Eiffel, Avenue Anatole France, París, Francia”. Además, te permite destacar las secciones de la descripción que coinciden con la búsqueda con el estilo que elijas mediante CharacterStyle. El parámetro CharacterStyle es opcional. Configúralo en nulo si no necesitas destacar nada.
• getPrimaryText(CharacterStyle) muestra el texto principal que describe un lugar. Suele ser 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 autocompletar. Ejemplos: “Avenida Anatole France, París, Francia” y “Sídney, Nueva Gales del Sur”.
• getPlaceId() muestra el ID de lugar de predicción. Un ID de lugar es un identificador textual que identifica un lugar de forma exclusiva y que puedes usar para recuperar el objeto Place 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 lineal en metros entre este lugar y el origen especificado en la solicitud.

Parámetros obligatorios

• Consulta

  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 Autocomplete (nuevo) muestra posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

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

Parámetros opcionales

• Tipos principales

  Una lista de hasta cinco tipos de valores de los tipos 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 asociado a los tipos Tabla A o Tabla B. 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.
  • Se especifican los 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, en una lista de hasta 15 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 tanto locationRestriction como includedRegionCodes, los resultados se ubicarán en el área de intersección de las dos configuraciones.

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

• Ajuste de entrada

  El desplazamiento del carácter 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 desplazamiento de entrada, llama al método setInputOffset() cuando compiles el objeto FindAutocompletePredictionsRequest.

• Sesgo o restricción de ubicación

  Puedes especificar una personalización o una restricción de ubicación, pero no ambas, para definir el área de búsqueda. Considera que la restricción de ubicación especifica la región donde deben encontrarse los resultados y el sesgo de ubicación es la región donde deben encontrarse los resultados. La diferencia clave es que, con el sesgo de ubicación, es posible que aún se muestren resultados fuera de la región especificada.

  • Sesgo de ubicación

    Especifica un área de búsqueda. Esta ubicación sirve como sesgo, no como restricción, de modo que es posible que se muestren resultados fuera del área especificada de todos modos.

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

  • Restricción de ubicación

    Especifica un área de búsqueda. No se muestran los 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 la personalización o la región de la restricción de ubicación como una Viewport rectangular o un círculo.

  • Un círculo se define por el punto central y el radio en metros. El radio debe ser entre 0.0 y 50,000.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 opuestos diagonalmente. Una viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben variar entre -90 y 90 grados inclusive, y los límites de longitud deben variar entre -180 y 180 grados inclusive:

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

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

• Origen

  Punto de origen desde el que se calcula la distancia en línea recta hasta el destino (al que se accede mediante 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

  El código regional que se usa para dar formato a la respuesta, incluido el formato de dirección, especificado como un valor de ccTLD ("dominio de nivel superior") de dos caracteres. 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á diseñado para representar la región desde donde se origina la solicitud, no necesariamente la región de destino 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 del código regional, 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 de Autocomplete (nuevo) como "sesiones". Autocomplete usa tokens de sesión para agrupar las fases de consulta y selección de la búsqueda con 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 finaliza 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, y 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 esta acción automáticamente).

  Autocomplete usa un AutocompleteSessionToken para identificar cada sesión. Tu app debe pasar un token de sesión nuevo al inicio de cada sesión nueva y, luego, pasar ese mismo token, junto con un ID de lugar, en la llamada posterior a fetchPlace() para recuperar Place Details para el lugar que seleccionó el usuario.

  Para establecer el parámetro del 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 autocompletado (nuevo)

Cómo usar la restricción y el sesgo de ubicación

Autocomplete (nuevo) usa la personalización de IP de forma predeterminada para controlar el área de búsqueda. Con la personalización de IP, la API utiliza la dirección IP del dispositivo para personalizar los resultados. De manera opcional, puedes usar la restricción de ubicación o el sesgo de ubicación, pero no ambas, para especificar el área en la que deseas realizar la búsqueda.

La restricción de ubicación especifica el área en la que se realizará la búsqueda. No se muestran los resultados fuera del área especificada. En el siguiente ejemplo, se usa una 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 sirve como sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera de ese área. 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());
        })
    );

Usar tipos principales

Usa el parámetro de tipos principales para restringir los resultados de una solicitud a un tipo determinado, como se muestra 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 principal para restringir los resultados a establecimientos del 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 quizás no deseas, como "athletic_field".

Usar 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 desde el origen hasta el destino en la respuesta (a la que se accede mediante 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 el autocompletado (nuevo) incluso sin un mapa. Si muestras un mapa, debe ser de Google. Cuando muestras predicciones del servicio Autocomplete (nuevo) sin un mapa, debes incluir el logotipo de Google que se muestra intercalado con el campo o los resultados de la búsqueda. Para obtener más información, consulta Muestra el logotipo de Google y las atribuciones.