Place Autocomplete

Desarrolladores del Espacio Económico Europeo (EEE)

El servicio de autocompletado en el SDK de Places para Android muestra predicciones de lugares como respuesta a las búsquedas de los usuarios. A medida que el usuario escribe, el servicio de autocompletado devuelve sugerencias de lugares, como empresas, direcciones, Plus Codes y lugares de interés.

Puedes agregar el autocompletado a tu aplicación de las siguientes formas:

Agrega un widget de autocompletar

El widget de autocompletar es un diálogo de búsqueda con una funcionalidad de autocompletar integrada. A medida que el usuario ingresa términos de búsqueda, el widget presenta una lista de lugares predichos para elegir. Cuando el usuario realiza una selección, se devuelve una instancia de Place, que tu app puede usar para obtener detalles sobre el lugar seleccionado.

Hay dos opciones para agregar el widget de autocompletado a tu aplicación:

Opción 1: Incorpora un AutocompleteSupportFragment

Para agregar un AutocompleteSupportFragment a tu app, sigue estos pasos:

  1. Agrega un fragmento al diseño XML de tu actividad.
  2. Agrega un objeto de escucha a tu actividad o fragmento.

Cómo agregar AutocompleteSupportFragment a una actividad

Para agregar AutocompleteSupportFragment a una actividad, agrega un nuevo fragmento a un diseño XML. Por ejemplo:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • De forma predeterminada, el fragmento no tiene límite ni fondo. Para proporcionar una apariencia visual coherente, anida el fragmento dentro de otro elemento de diseño, como un CardView.
  • Si usas el fragmento de Autocomplete y necesitas anular onActivityResult, debes llamar a super.onActivityResult. De lo contrario, el fragmento no funcionará correctamente.

Agrega un PlaceSelectionListener a una actividad

El PlaceSelectionListener controla la devolución de un lugar como respuesta a la selección del usuario. En el siguiente código, se muestra la creación de una referencia al fragmento y la adición de un objeto de escucha a tu AutocompleteSupportFragment:

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Opción 2: Usa un intent para iniciar la actividad de autocompletar

Si quieres que tu app use un flujo de navegación diferente (por ejemplo, para activar la experiencia de autocompletar desde un ícono en lugar de un campo de búsqueda), tu app puede iniciar el autocompletado con un intent.

Para iniciar el widget de autocompletado por medio de una intent, sigue estos pasos:

  1. Usa Autocomplete.IntentBuilder para crear una intención y pasar el modo Autocomplete deseado.
  2. Define un objeto de inicio de resultados de actividad registerForActivityResult que se puede usar para iniciar el intent y controlar la predicción de lugar seleccionada por el usuario en el resultado.

Crea un intent de autocompletado

En el siguiente ejemplo, se usa Autocomplete.IntentBuilder para crear un intent que inicie el widget de autocompletado como un intent:

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

Cuando usas un intent para iniciar el widget de autocompletar, puedes elegir entre los modos de visualización de superposición o de pantalla completa. En las siguientes capturas de pantalla, se muestra cada modo de visualización, respectivamente:

Cuando se muestra en modo de superposición, el widget de autocompletar aparece superpuesto sobre la IU de llamada.
Figura 1: Widget de autocompletado en modo OVERLAY
Cuando se muestra en modo de pantalla completa, el widget de autocompletar ocupa toda la pantalla.
Figura 2: Widget de autocompletar en modo de PANTALLA COMPLETA

Cómo registrar una devolución de llamada para el resultado de la intención

Para recibir una notificación cuando el usuario haya seleccionado un lugar, define un objeto de lanzamiento registerForActivityResult(), que inicia la actividad y también controla el resultado, como se muestra en el siguiente ejemplo. Si el usuario seleccionó una predicción, se entregará en el intent contenido en el objeto del resultado. Debido a que el intent se creó con Autocomplete.IntentBuilder, el método Autocomplete.getPlaceFromIntent() puede extraer el objeto Place.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Cómo obtener predicciones de lugares de forma programática

Puedes crear una IU de búsqueda personalizada como alternativa a la IU que proporciona el widget de autocompletar. Para ello, tu app debe obtener predicciones de lugares de forma programática. Tu app puede obtener una lista de nombres o direcciones de lugares predichos de la API de Autocomplete llamando a PlacesClient.findAutocompletePredictions() y pasando un objeto FindAutocompletePredictionsRequest con los siguientes parámetros:

  • Obligatorio: Es una cadena query que contiene el texto que escribió el usuario.
  • Recomendado: Un AutocompleteSessionToken, que agrupa las fases de consulta y selección de la búsqueda de un usuario en una sesión discreta para fines de facturación. La sesión comienza cuando el usuario comienza a escribir una consulta y termina cuando selecciona un lugar.
  • Recomendado: Un objeto RectangularBounds que especifica los límites de latitud y longitud para restringir los resultados a la región especificada.
  • Opcional: Uno o más códigos de país de dos letras (ISO 3166-1, Alpha-2) que indican el país o los países a los que se deben restringir los resultados.
  • Opcional: Un TypeFilter que puedes usar para restringir los resultados al tipo de lugar especificado. Se admiten los siguientes tipos de lugares:

    • TypeFilter.GEOCODE: Muestra solo resultados de geocodificación, no empresas. Usa esta solicitud para eliminar las ambigüedades de los resultados en los que la ubicación especificada puede ser indeterminada.
    • TypeFilter.ADDRESS: Muestra solo los resultados de autocompletar con una dirección precisa. Usa este tipo cuando sepas que el usuario busca una dirección específica precisa.
    • TypeFilter.ESTABLISHMENT: Devuelve solo los lugares que son empresas.
    • TypeFilter.REGIONS: Muestra solo los lugares que coinciden con uno de los siguientes tipos:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES: Muestra solo los resultados que coinciden con LOCALITY o ADMINISTRATIVE_AREA_LEVEL_3.

  • Opcional: Un objeto LatLng que especifica la ubicación de origen de la solicitud. Cuando llamas a setOrigin(), el servicio devuelve la distancia en metros (distanceMeters) desde el origen especificado para cada predicción de autocompletar en la respuesta.

Para obtener información sobre los tipos de lugar, consulta la guía sobre tipos de lugar.

En el siguiente ejemplo, se muestra una llamada completa a PlacesClient.findAutocompletePredictions().

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

La API devuelve un FindAutocompletePredictionsResponse en un Task. El objeto FindAutocompletePredictionsResponse contiene una lista de 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 el 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 el SDK de Places para Android, consulta Place Details. Para obtener información general sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.
  • getPlaceTypes() muestra 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.

Tokens de sesión

Los tokens de sesión agrupan 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 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. Tu app debe generar un token nuevo para cada sesión. Recomendamos usar tokens de sesión para todas las sesiones de autocompletado programáticas (cuando incorporas un fragmento o inicias el autocompletado con una intención, la API se encarga de esto automáticamente).

El SDK de Places para Android usa un AutocompleteSessionToken para identificar cada sesión. Tu app debe pasar un token de sesión nuevo al comienzo 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 los detalles del lugar que seleccionó el usuario.

Obtén más información sobre los tokens de sesión.

Cómo restringir los resultados de autocompletar

Puedes restringir los resultados de autocompletado a una región geográfica específica o filtrar los resultados según uno o más tipos de lugares, o bien hasta cinco países. Puedes aplicar estas restricciones a la actividad de autocompletado, AutocompleteSupportFragment y las APIs de autocompletado programático.

Para restringir los resultados, haz lo siguiente:

  • Para priorizar los resultados dentro de la región definida, llama a setLocationBias() (es posible que se devuelvan algunos resultados de fuera de la región definida).
  • Para solo mostrar resultados dentro de la región definida, llama a setLocationRestriction() (solo se devolverán los resultados dentro de la región definida).
  • Para mostrar solo los resultados que se ajustan a un tipo de lugar en particular, llama a setTypesFilter() (por ejemplo, si especificas TypeFilter.ADDRESS, se mostrarán solo los resultados con una dirección precisa).
  • Para devolver solo los resultados de hasta cinco países especificados, llama a setCountries(). Los países se deben pasar como un código de país compatible con ISO 3166-1 Alpha-2 de dos caracteres.

Personaliza los resultados según una región específica

Para personalizar los resultados de autocompletado según una región geográfica específica, llama a setLocationBias() y pasa un RectangularBounds. En el siguiente ejemplo de código, se muestra cómo llamar a setLocationBias() en una instancia de fragmento para sesgar sus sugerencias de autocompletado hacia una región de Sídney, Australia.

Kotlin

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Cómo restringir los resultados a una región específica

Para restringir los resultados del autocompletado a una región geográfica específica, llama a setLocationRestriction() y pasa un RectangularBounds. En el siguiente ejemplo de código, se muestra cómo llamar a setLocationRestriction() en una instancia de fragmento para sesgar sus sugerencias de autocompletado hacia una región de Sídney, Australia.

Kotlin

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Nota: Esta restricción solo se aplica a las rutas completas. Los resultados sintéticos ubicados fuera de los límites rectangulares se pueden mostrar solo si la ruta correspondiente se superpone con la restricción de ubicación.

Cómo filtrar los resultados por tipos de lugares o colecciones de tipos

Puedes restringir los resultados de una solicitud de autocompletado para que solo muestren un determinado tipo de lugar. Especifica un filtro con los tipos de lugar o una colección de tipos que se indican en las tablas 1, 2 y 3 de Tipos de lugares. Si no se especifica nada, se devuelven todos los tipos.

Para filtrar los resultados de autocompletar, llama a setTypesFilter() para establecer el filtro.

Para especificar un filtro de tipo o de colección de tipos, haz lo siguiente:

  • Llama a setTypesFilter() y especifica hasta cinco valores de type de las tablas 1 y 2 que se muestran en Tipos de lugar. Los valores de tipo se definen mediante las constantes en PlaceTypes.

  • Llama a setTypesFilter() y especifica una colección de tipos de la tabla 3 que se muestra en Tipos de lugares. Los valores de la colección se definen mediante las constantes en PlaceTypes.

    Solo se permite un tipo de la Tabla 3 en la solicitud. Si especificas un valor de la Tabla 3, no puedes especificar un valor de la Tabla 1 o de la Tabla 2. Si lo haces, se produce un error.

En el siguiente ejemplo de código, se llama a setTypesFilter() en un AutocompleteSupportFragment y se especifican varios valores de tipo.

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

Java

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

En el siguiente ejemplo de código, se muestra cómo llamar a setTypesFilter() en un AutocompleteSupportFragment para establecer un filtro que solo devuelva resultados con una dirección precisa especificando una colección de tipos.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

En el siguiente ejemplo de código, se muestra cómo llamar a setTypesFilter() en un IntentBuilder para establecer un filtro que solo muestre resultados con una dirección precisa especificando una colección de tipos.

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

Java

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Cómo filtrar los resultados por país

Para filtrar los resultados de autocompletado hasta en cinco países, llama a setCountries() para establecer el código de país. Luego, pasa el filtro a un fragmento o una intent. Los países se deben pasar como un código de país compatible con ISO 3166-1 Alpha-2 de dos caracteres.

En el siguiente ejemplo de código, se muestra cómo llamar a setCountries() en un AutocompleteSupportFragment para establecer un filtro que solo muestre los resultados de los países especificados.

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

      

Java

    autocompleteFragment.setCountries("AU", "NZ");

      

Límites de uso

Tu uso de la API de Places, incluido el SDK de Places para Android, ya no está limitado a una cantidad máxima de solicitudes por día (QPD). Sin embargo, se siguen aplicando los siguientes límites de uso:

  • El límite de frecuencia es de 6,000 QPM (solicitudes por minuto). Se calcula como la suma de las solicitudes del cliente y del servidor para todas las aplicaciones que usan las credenciales del mismo proyecto.

Mostrar atribuciones en tu aplicación

  • Si tu app usa el servicio de autocompletado de forma programática, tu IU debe mostrar una atribución de "Con tecnología de Google" o aparecer dentro de un mapa con la marca de Google.
  • Si tu app usa el widget de autocompletado, no se requiere ninguna acción adicional (la atribución requerida se muestra de forma predeterminada).
  • Si recuperas y muestras información adicional del lugar después de obtener un lugar por ID, también debes mostrar las atribuciones de terceros.

Para obtener más detalles, consulta la documentación sobre las atribuciones.

Optimización de Place Autocomplete (legacy)

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

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

Optimización avanzada de los costos

Considera utilizar la implementación programática de Place Autocomplete (legacy) para acceder a los precios por solicitud y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details (legacy). Los precios por pedido 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 (Legacy).
  • Si los usuarios seleccionan una predicción de autocompletar con un promedio de cuatro solicitudes o menos de predicciones de Place Autocomplete (legacy), el precio por solicitud puede ser más rentable que el precio por sesión.
Si necesitas ayuda para elegir la implementación de Place Autocomplete (heredado) más adecuada para tus necesidades, selecciona la pestaña correspondiente a tu respuesta en función de la siguiente pregunta.

¿Tu aplicación requiere algún dato diferente de la dirección y las coordenadas de latitud o longitud de la predicción seleccionada?

Sí, necesita más detalles

Usa el servicio Place Autocomplete basado en sesiones (heredado) con Place Details (heredado).
Dado que tu aplicación requiere Place Details (Legacy), como el nombre del lugar, el estado de la empresa o el horario de atención, tu implementación de Place Autocomplete (Legacy) debe usar un token de sesión (de forma programática o integrado en los widgets de JavaScript, Android o iOS). por sesión más los SKU de Places Data aplicables según los campos de datos de lugares que solicites.1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android o iOS. Esto incluye las solicitudes de Place Autocomplete (legado) y Place Details (legado) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos de datos de lugar que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete (Legacy). Cuando solicites la predicción seleccionada a Place Details (Legacy), incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Place Autocomplete (Legacy)
  2. El token de sesión que se usó en la solicitud de Place Autocomplete (legado)
  3. El parámetro fields que especifica los campos de datos de lugar que necesitas

No, solo requiere la dirección y la ubicación

La API de Geocoding podría ser una opción más rentable que Place Details (Legacy) para tu aplicación, según el rendimiento de tu uso de Place Autocomplete (Legacy). La eficiencia de Place Autocomplete (legacy) de cada aplicación varía según las búsquedas que ingresan los usuarios, dónde se usa la aplicación y si se siguen las prácticas recomendadas de optimización del rendimiento.

Para responder la siguiente pregunta, analiza cuántos caracteres escribe un usuario en promedio antes de seleccionar una predicción de Place Autocomplete (legado) en tu aplicación.

¿Tus usuarios seleccionan, en promedio, una predicción de Place Autocomplete (Legacy) cada cuatro solicitudes o menos?

Implementa Place Autocomplete (Legacy) de manera programática sin tokens de sesión y llama a la API de Geocoding en la predicción de lugar seleccionada.
La API de Geocoding proporciona direcciones y coordenadas de latitud y longitud. Realizar cuatro solicitudes de Place Autocomplete (legacy) - Per Request más una llamada a la API de Geocoding sobre la predicción de lugar seleccionada es inferior al costo por sesión de Place Autocomplete (legacy) por sesión.1

Considera aplicar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

No

Usa el servicio Place Autocomplete basado en sesiones (heredado) con Place Details (heredado).
Dado que la cantidad promedio de solicitudes que esperas realizar antes de que un usuario seleccione una predicción de Place Autocomplete (Legacy) supera el costo de los precios por sesión, tu implementación de Place Autocomplete (Legacy) debe usar un token de sesión para las solicitudes de Place Autocomplete (Legacy) y la solicitud de Place Details (Legacy) asociada por sesión.1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android o iOS. Esto incluye las solicitudes de Place Autocomplete (legado) y Place Details (legado) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente campos de datos básicos.

Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete (Legacy). Cuando solicites la predicción seleccionada a Place Details (Legacy), incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Place Autocomplete (Legacy)
  2. El token de sesión que se usó en la solicitud de Place Autocomplete (legado)
  3. El parámetro fields que especifica campos de datos básicos, como la dirección y la geometría

Considera retrasar las solicitudes de Place Autocomplete (Legacy)
Puedes emplear estrategias como demorar una solicitud de Place Autocomplete (Legacy) hasta que el usuario escriba los primeros tres o cuatro caracteres para que tu aplicación realice menos solicitudes. Por ejemplo, realizar solicitudes de Place Autocomplete (Legacy) para cada carácter después de que el usuario haya escrito el tercer carácter significa que, si el usuario escribe siete caracteres y, luego, selecciona una predicción para la que realizas una solicitud a la API de Geocoding, el costo total será el de 4 solicitudes de Place Autocomplete (Legacy) por solicitud más Geocoding.1

Si retrasar las solicitudes puede hacer que tu solicitud programática promedio sea inferior a cuatro, puedes seguir las instrucciones para implementar Place Autocomplete (legado) con la API de Geocoding y obtener un rendimiento optimizado. Ten en cuenta que demorar las solicitudes puede percibirse como latencia por parte del usuario, que tal vez espere ver predicciones con cada letra que ingresa.

Considera seguir las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.


  1. Para conocer los costos, consulta las listas de precios de Google Maps Platform.

Prácticas recomendadas para el rendimiento

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

  • 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 Place Autocomplete (Legacy). 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 Place Autocomplete (heredado) 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 Place Autocomplete (Legacy), 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 únicamente información sobre la dirección, vuelve a usar su entrada original 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 Find Place (heredada). 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 subpremisa, 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 Place Autocomplete (legacy).
    • 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

Solución de problemas

Si bien pueden ocurrir una gran variedad de errores, la mayoría de los que es probable que experimente tu app suelen deberse a errores de configuración (por ejemplo, se usó la clave de API incorrecta o se configuró de forma incorrecta) o a errores de cuota (tu app excedió su cuota). Consulta Límites de uso para obtener más información sobre las cuotas.

Los errores que se producen durante el uso de los controles de autocompletar se devuelven en la devolución de llamada onActivityResult(). Llama a Autocomplete.getStatus() para obtener el mensaje de estado del resultado.