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 de autocompletar puede coincidir en palabras completas y subcadenas de la entrada, 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, puedes llamar a Autocomplete utilizando como entrada un string que contiene una entrada parcial del usuario, "Sicilian piz", con el área de búsqueda limitado a San Francisco, CA. La respuesta luego contiene una lista de lugares predicciones que coinciden con la cadena y el área de búsqueda, como el restaurante, llamada "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 crear un Place Details (Nuevo) para obtener más información sobre ninguna de las predicciones de sitios mostradas.

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 tu SDK versión. 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 a Autocomplete (nuevas)

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. El siguiente ejemplo 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: Llamadas realizadas con Place Autocomplete widgets llamar siempre a Place Autocomplete, no Place Autocomplete (nuevo); las llamadas a widgets no se ven afectadas 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 según el criterio del mejor esfuerzo. Una vez que se emite una solicitud de cancelación, no se devuelve ninguna respuesta. Emitir un token de cancelación NO garantiza que una solicitud en particular se cancelará y es posible que se te cobre la solicitud incluso si no se muestra una respuesta inicial.

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 hay lugar conocido correspondiente a la consulta y los criterios de filtro.

Para cada sitio de predicción, puedes realizar una llamada a los siguientes métodos a fin de recuperar datos de sitios detalles:

• getFullText(CharacterStyle) muestra el texto completo de una descripción de lugar. Esta es una combinación texto principal 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 coincida con la búsqueda con el estilo que elijas, mediante 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 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: “Avenida Anatole France, París, Francia” y “Sídney, 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). En general información sobre los IDs de lugar, consulta el artículo ID de lugar descripción general.
• getTypes() muestra la lista de tipos de lugares asociados con este sitio.
• 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 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

  Una lista de hasta cinco tipos de valores de tipos Tabla A o la Tabla B que se usa para filtrar los sitios devueltos en la respuesta. Un sitio debe coincidir con uno de los valores de tipo primario especificado que se incluirán 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.
  • Se especifican todos los tipos no reconocidos.

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

• Países

  Incluye solo los 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:

  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 countries, llama a 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 o restricción de la 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 la búsqueda. La ubicación es un sesgo, no una restricción, por lo que los resultados fuera del área especificada.

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

  • Restricción de ubicación

    Especifica un área para la búsqueda. No se muestran resultados fuera del área especificada.

    Para establecer el parámetro de restricción de ubicación, llama a 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 50, 000.0 inclusive. El valor predeterminado es 0.0. Para las restricciones de ubicación, debe 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 un región cerrada, lo que significa que incluye su límite. Los límites de latitud debe variar entre -90 y 90 grados inclusive, y los límites de longitud debe oscilar entre -180 y 180 grados inclusive:

    Nota: Los tipos de personalización admitidos varían según la versión del SDK. que estás usando. 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, el viewport 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 debe especificar como coordenadas de latitud y longitud:

  Para establecer el parámetro de origen, llama a 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 Llamadas de Autocomplete (nuevas) como "sesiones". Autocomplete usa tokens de sesión para agrupar las fases de consulta y selección de una búsqueda de autocompletado del usuario en una sesión discreta para 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 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. Recomendamos usar tokens de sesión para todas las actividades sesiones de autocompletado (cuando incorporas un fragmento o inicias el autocompletado usando 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 inicies 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 del token de sesión, llama a 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. Si lo deseas, puedes usar la ubicación restricción o sesgo de ubicación, pero no ambos, para especificar un área de búsqueda.

La restricción de ubicación especifica el área a buscar. 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());
        })
    );

Usar 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 “Soccer” y usa el método principal Parámetro de tipos 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 del origen al destino en la respuesta (al 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.