Autocompletar (nuevo)

Autocomplete (nuevo) devuelve 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, y resolver nombres de lugares, direcciones y Plus Codes. Tu aplicación puede enviar búsquedas a medida que el usuario escribe para proporcionar predicciones de lugares y búsquedas en el momento.

Por ejemplo, llamas a Autocomplete con una cadena que contiene una entrada parcial del usuario, "pizza siciliana", 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 devuelven están diseñadas para presentarse al usuario y ayudarlo a seleccionar el lugar deseado. Puedes realizar una solicitud de Place Details (nuevo) para obtener más información sobre cualquiera de las predicciones de lugares devueltas.

Puedes integrar la funcionalidad de Autocomplete (nuevo) en tu app de dos maneras principales:

• Agrega el widget de Place Autocomplete: Proporciona una experiencia de autocompletar de búsqueda lista para usar a través de la clase PlaceAutocomplete que muestra predicciones a medida que el usuario escribe.
• Obtén predicciones de lugares de forma programática: Llama a la API directamente para recuperar predicciones y mostrarlas en una interfaz de usuario personalizada.

Agrega el widget de Place Autocomplete

Para proporcionar con mayor facilidad una experiencia de autocompletar lugares coherente, puedes agregar el widget de Place Autocomplete a tu app. El widget proporciona una interfaz de pantalla completa dedicada que controla la entrada del usuario y muestra predicciones de lugares al usuario mientras devuelve objetos AutocompletePrediction a la app. Luego, puedes realizar una solicitud de Place Details (nuevo) para obtener información adicional sobre cualquiera de las predicciones de lugares.

Al igual que cuando obtienes predicciones de lugares de forma programática, el widget de Place Autocomplete te permite usar tokens de sesión para agrupar las solicitudes de autocompletado en sesiones a los fines de facturación. Puedes pasar un token de sesión cuando creas la intención para el widget llamando a setAutocompleteSessionToken(). Si no proporcionas un token de sesión, el widget creará uno para ti, al que podrás acceder llamando a getSessionTokenFromIntent(). Para obtener más información sobre el uso de tokens de sesión, consulta Acerca de los tokens de sesión.

Para agregar el widget de Place Autocomplete a tu app, haz lo siguiente:

1. (Opcional) Define un token de sesión. Si no proporcionas un token de sesión, el widget creará uno por ti.

2. Define un objeto autocompleteIntent con los parámetros deseados y tu token de sesión.

3. Define un ActivityResultLauncher para StartActivityForResult. Este objeto Launcher controlará el resultado que se devuelva de la actividad de autocompletar.

4. Controla el resultado en la devolución de llamada de ActivityResultLauncher. Esto implica extraer AutocompletePrediction y AutocompleteSessionToken (si no proporcionaste los tuyos), controlar errores y, de manera opcional, realizar una solicitud de fetchPlace() para obtener detalles adicionales sobre un lugar.

5. Inicia el intent con placeAutocompleteActivityResultLauncher

En los siguientes ejemplos, se muestra cómo agregar el widget de Place Autocomplete con Kotlin y Java:

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Cómo personalizar el tema

Cuando creas una instancia de una experiencia de Autocomplete, puedes especificar un tema que anule cualquiera de los atributos de diseño predeterminados. Puedes personalizar los colores, la tipografía, el espaciado, los bordes y las esquinas de tu componente de Place Autocomplete. El valor predeterminado es PlacesMaterialTheme. Los atributos de tema que no se anulan usan los estilos predeterminados.

Puedes definir anulaciones de temas en …/res/values/themes.xml. Por ejemplo:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Luego, puedes hacer referencia a los diseños de anulación llamando a setAutocompleteUiCustomization:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Obtén predicciones de lugares de forma programática

Tu app puede obtener una lista de nombres o direcciones de lugares predichos 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());
        })
    );

Respuestas de Autocomplete (nuevo)

La API devuelve un objeto FindAutocompletePredictionsResponse en un objeto Task. El objeto FindAutocompletePredictionsResponse contiene una lista de hasta cinco objetos AutocompletePrediction que representan lugares predichos. La lista puede estar vacía si no hay ningún lugar conocido que corresponda a la búsqueda y a los criterios de filtro.

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

• getFullText(CharacterStyle) devuelve el texto completo de la descripción de un lugar. Es una combinación del texto principal y secundario. Ejemplo: "Torre Eiffel, Avenue Anatole France, París, 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. Establécelo como nulo si no necesitas ningún destacado.
• getPrimaryText(CharacterStyle) devuelve el texto principal que describe un lugar. Por lo general, es el nombre del lugar. Ejemplos: "Torre Eiffel" y "123 Pitt Street".
• getSecondaryText(CharacterStyle) devuelve 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() devuelve el ID del lugar predicho. Un ID de lugar es un identificador textual que identifica un lugar de forma única y 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() devuelve la lista de tipos de lugar asociados con este lugar.
• getDistanceMeters() devuelve 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) devuelve posibles coincidencias en función de esta cadena y ordena los resultados según su relevancia percibida.

  Para establecer 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 incluirse 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

  Solo se incluyen los resultados de la lista de países especificados, que se indican como una lista de hasta 15 valores de dos caracteres del ccTLD ("dominio de nivel superior"). 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 ubicarán en el área de intersección de ambos 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 del carácter Unicode basado en cero que indica la posición del cursor en la búsqueda. 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 restricción o una preferencia 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 dentro de la cual deben estar los resultados, y en el sesgo de ubicación como la especificación de la región cerca de la cual deben estar los resultados. La diferencia clave es que, con el sesgo de ubicación, es posible que se sigan devolviendo resultados fuera de la región especificada.

  • Sesgo de ubicación

    Especifica un área para la búsqueda. Esta ubicación sirve como sesgo, no como restricción, por lo que es posible que se devuelvan 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 la 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 región de restricción o sesgo de ubicación como un viewport rectangular o como un círculo.

  • Un círculo se define por un punto central y un radio en metros. El radio debe estar entre 0.0 y 50000.0, ambos incluidos. El valor predeterminado es 0.0. En el caso de la restricción de ubicación, debes establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud no devolverá ningún resultado.

  • Un rectángulo es un viewport de latitud y longitud, representado como dos puntos low y high opuestos diagonalmente. 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 ventana gráfica incluye todas las longitudes.
    • Si low.longitude = 180 grados y high.longitude = -180 grados, el rango de longitud está vacío.

    Se deben completar 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 (se accede con getDistanceMeters()). Si se omite este valor, no se devolverá 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 del 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 "El Reino Unido de Gran Bretaña e Irlanda del Norte").

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

  Para configurar el parámetro del 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), tanto las que se realizan a través del widget como las programáticas, como "sesiones". Autocomplete usa tokens de sesión para agrupar las fases de consulta y selección de una búsqueda con autocompletado del usuario en una sesión discreta para fines de facturación. La sesión comienza cuando el usuario comienza a escribir una búsqueda 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, por lo que tu app debe generar un token nuevo para cada sesión. Recomendamos usar tokens de sesión para todas las sesiones de autocompletado programático (cuando incorporas un fragmento o inicias el autocompletado con una intención, la API se encarga de esto automáticamente).

  El autocompletado usa un AutocompleteSessionToken para identificar cada sesión. Tu app debe pasar un token de sesión nuevo cuando comience 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 configurar 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 Autocomplete (nuevo)

Usa la restricción y la adaptación de la ubicación

De forma predeterminada, Autocomplete (nuevo) usa la adaptación de IP para controlar el área de búsqueda. Con la adaptación de IP, la API usa la dirección IP del dispositivo para adaptar 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 de búsqueda.

La restricción de ubicación especifica el área de búsqueda. No se devuelven 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 centrada 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 la personalización según la ubicación, esta sirve como sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los que se encuentran fuera del área especificada. En el siguiente ejemplo, se cambia la solicitud anterior para usar la preferencia 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 primarios

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 devuelven todos los tipos.

En el siguiente ejemplo, se especifica una cadena de búsqueda de "Fútbol" y se usa el parámetro primarytypes 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 tal vez no desees, 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 (se accede a ella con getDistanceMeters()). Este ejemplo 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());
        })
    );

Optimización de Autocomplete (nuevo)

En esta sección, se describen algunas prácticas recomendadas que te ayudarán a aprovechar al máximo el servicio Autocomplete (nuevo).

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 (nuevo) de la API de Maps JavaScript, el widget de Autocomplete (nuevo) del SDK de Places para Android o el widget de Autocomplete (nuevo) del SDK de Places para iOS.
• Comprende los campos de datos esenciales de Autocomplete (nuevo) 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 Autocomplete (nuevo), usa máscaras de campo en los widgets de Place Details (nuevo) y Autocomplete (nuevo) para mostrar solo los campos de datos de Autocomplete (nuevo) que necesitas.

Optimización avanzada de los costos

Considera utilizar la implementación programática de Autocomplete (nuevo) para acceder a los SKU: precios de solicitudes de Autocomplete y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details (nuevo). Los precios por solicitud 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 (nuevo).
• 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 el rendimiento

Los siguientes lineamientos describen maneras de optimizar el rendimiento de Autocomplete (nuevo):

• 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 Autocomplete (nuevo). 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 Autocomplete (nuevo) 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 (nuevo), 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 solo información de la dirección, reutiliza la entrada original del usuario 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 Place Details (nuevo). 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 subinstalaciones, como direcciones de unidades o apartamentos específicos dentro de un edificio Por ejemplo, la dirección checa "Stroupežnického 3191/17, Praha" genera una predicción parcial en Autocomplete (nuevo).
  • 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

Ajuste de la ubicación

Personaliza los resultados para un área específica pasando un parámetro location y un parámetro radius. Esto indica a Autocomplete (nuevo) que prefiera mostrar resultados dentro del área definida. Es posible que también se muestren resultados externos al área definida. Puedes usar el parámetro components para filtrar los resultados y mostrar solo los lugares dentro de un país especificado.

Restricción de ubicación

Restringe los resultados a un área específica pasando un parámetro locationRestriction.

También puedes restringir los resultados a la región definida por location y un parámetro radius agregando el parámetro locationRestriction. Esto indica a Autocomplete (nuevo) que muestre solo los resultados dentro de esa región.