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. 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, California. 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 muestran están diseñadas para presentarlas 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.

Solicitudes a Autocomplete (nuevo)

Para obtener una lista de nombres de lugares o direcciones predichos de la API de Autocomplete, llama a PlacesClient.findAutocompletePredictions() y pasa 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());
        })
    );

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 un lugar 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 los detalles del lugar:

  • getFullText(CharacterStyle) muestra el texto completo de la descripción de un lugar. Esta es una combinación del texto primario y secundario. Ejemplo: "Torre Eiffel, Avenue Anatole France, Paris, Francia". Además, este método te permite destacar las secciones de la descripción que coinciden con la búsqueda con un estilo de tu elección usando CharacterStyle. El parámetro CharacterStyle es opcional. Configúralo como nulo si no necesitas ningún elemento destacado.
  • getPrimaryText(CharacterStyle) muestra el texto principal que describe un lugar. Por lo general, es el nombre del lugar. Ejemplos: "Torre Eiffel" y "123 Pitt Street".
  • getSecondaryText(CharacterStyle) muestra el texto secundario de la descripción de un lugar. Esto es útil, por ejemplo, como segunda línea cuando se muestran predicciones de autocompletado. Ejemplos: "Avenue Anatole France, Paris, France" y "Sydney, New South Wales".
  • getPlaceId() muestra el ID del lugar previsto. Un ID de lugar es un identificador textual que identifica un lugar de forma exclusiva, que puedes usar para recuperar el objeto Place más adelante. 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 realizará 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

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

    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, 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 un sesgo, 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 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 diagonalmente opuestos. Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben estar entre -90 y 90 grados inclusive, y los límites de longitud deben estar entre -180 y 180 grados inclusive:

      • 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, la vista 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 de 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”).

    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 los 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 Maps. Cuando muestres predicciones del servicio 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.