Place Autocomplete

Il servizio di completamento automatico in Places SDK per Android restituisce le predizioni relative ai luoghi in risposta alle query di ricerca degli utenti. Man mano che l'utente digita, il servizio di completamento automatico restituisce suggerimenti per luoghi come attività, indirizzi, plus code e punti d'interesse.

Puoi aggiungere il completamento automatico alla tua app nei seguenti modi:

• Aggiungi un widget di completamento automatico per risparmiare tempo in fase di sviluppo e garantire un'esperienza utente coerente.
• Ricevi le previsioni dei luoghi in modo programmatico per creare un'esperienza utente personalizzata.

Aggiungere un widget di completamento automatico

Il widget di completamento automatico è una finestra di dialogo di ricerca con funzionalità di completamento automatico integrata. Quando un utente inserisce i termini di ricerca, il widget presenta un elenco di luoghi previsti tra cui scegliere. Quando l'utente effettua una selezione, viene restituita un'istanza di Place che la tua app può utilizzare per ottenere i dettagli del luogo selezionato.

Esistono due opzioni per aggiungere il widget di completamento automatico alla tua app:

• Opzione 1: incorpora un AutocompleteSupportFragment.
• Opzione 2: utilizza un'intenzione per avviare l'attività di completamento automatico.

Opzione 1: incorpora un elemento AutocompleteSupportFragment

Per aggiungere un AutocompleteSupportFragment alla tua app:

1. Aggiungi un frammento al layout XML dell'attività.
2. Aggiungi un listener all'attività o al frammento.

Aggiungere AutocompleteSupportFragment a un'attività

Per aggiungere AutocompleteSupportFragment a un'attività, aggiungi un nuovo frammento a un layout XML. Ad esempio:

<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"
  />

• Per impostazione predefinita, il frammento non ha bordi o sfondo. Per fornire un aspetto visivo coerente, nidifica il frammento all'interno di un altro elemento di layout, ad esempio un CardView.
• Se utilizzi il frammento di completamento automatico e devi eseguire l'override di onActivityResult, devi chiamare super.onActivityResult, altrimenti il frammento non funzionerà correttamente.

Aggiungere un PlaceSelectionListener a un'attività

PlaceSelectionListener gestisce la restituzione di un luogo in risposta alla selezione dell'utente. Il seguente codice mostra la creazione di un riferimento al frammento e l'aggiunta di un listener al tuo AutocompleteSupportFragment:

    // 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")
        }
    })

      

    // 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);
        }
    });

      

Opzione 2: utilizza un'intenzione per avviare l'attività di completamento automatico

Se vuoi che la tua app utilizzi un flusso di navigazione diverso (ad esempio per attivare l'esperienza di completamento automatico da un'icona anziché da un campo di ricerca), la tua app può avviare il completamento automatico utilizzando un'intenzione.

Per avviare il widget di completamento automatico utilizzando un'intenzione:

1. Utilizza Autocomplete.IntentBuilder per creare un'intenzione, passando la modalità Autocomplete desiderata.
2. Definisci un comando di avvio del risultato dell'attività registerForActivityResult che può essere utilizzato per avviare l'intent e gestire la previsione del luogo selezionato dall'utente nel risultato.

Creare un'intenzione di completamento automatico

L'esempio seguente utilizza Autocomplete.IntentBuilder per creare un intent per avviare il widget di completamento automatico come intent:

    // 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)

      

    // 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);

      

Quando utilizzi un'intent per avviare il widget di completamento automatico, puoi scegliere tra le modalità di visualizzazione in overlay o a schermo intero. Gli screenshot seguenti mostrano ciascuna modalità di visualizzazione:

Registra un callback per il risultato dell'intent

Per ricevere una notifica quando l'utente ha selezionato un luogo, definisci un avviatore registerForActivityResult(), che avvia l'attività e gestisce anche il risultato, come mostrato nell'esempio seguente. Se l'utente ha selezionato una previsione, questa verrà inviata nell'intent contenuto nell'oggetto del risultato. Poiché l'intent è stato creato da Autocomplete.IntentBuilder, il metodo Autocomplete.getPlaceFromIntent() può estrarre l'oggetto Place.

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")
        }
    }

      

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");
            }
        });

      

Ottenere le previsioni dei luoghi in modo programmatico

Puoi creare un'interfaccia utente di ricerca personalizzata come alternativa a quella fornita dal widget di completamento automatico. Per farlo, l'app deve ricevere le previsioni dei luoghi programmaticamente. La tua app può ottenere un elenco di nomi di luoghi e/o indirizzi previsti dall'API di completamento automatico chiamando PlacesClient.findAutocompletePredictions(), passando un oggetto FindAutocompletePredictionsRequest con i seguenti parametri:

• Obbligatorio: una stringa query contenente il testo digitato dall'utente.
• Consigliato: un AutocompleteSessionToken, che raggruppa le fasi di query e selezione di una ricerca dell'utente in una sessione distinta a fini di fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo.
• Consigliato:un oggetto RectangularBounds che specifica i limiti di latitudine e longitudine per limitare i risultati alla regione specificata.
• Facoltativo:uno o più codici paese (ISO 3166-1 alpha-2) di due lettere che indicano il paese o i paesi a cui devono essere limitati i risultati.

• Facoltativo:un valore TypeFilter, che puoi utilizzare per limitare i risultati al tipo di luogo specificato. Sono supportati i seguenti tipi di luoghi:

  • TypeFilter.GEOCODE: restituisce solo i risultati di geocodifica, anziché le attività. Utilizza questa richiesta per distinguere i risultati in cui la località specificata potrebbe essere indeterminata.
  • TypeFilter.ADDRESS: restituisce solo i risultati del completamento automatico con un indirizzo preciso. Utilizza questo tipo quando sai che l'utente sta cercando un indirizzo completamente specificato.
  • TypeFilter.ESTABLISHMENT: restituisce solo i luoghi che sono attività.

  • TypeFilter.REGIONS: restituisce solo i luoghi che corrispondono a uno dei seguenti tipi:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES: restituisce solo i risultati corrispondenti a LOCALITY o ADMINISTRATIVE_AREA_LEVEL_3.

• (Facoltativo) Un LatLng che specifica la località di origine della richiesta. Quando chiami setOrigin(), il servizio restituisce la distanza in metri (distanceMeters) dall'origine specificata per ogni previsione di completamento automatico nella risposta.

Per informazioni sui tipi di luoghi, consulta la guida ai tipi di luoghi.

L'esempio seguente mostra una chiamata completa a PlacesClient.findAutocompletePredictions().

    // 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}")
            }
        }

      

    // 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());
        }
    });

      

L'API restituisce un FindAutocompletePredictionsResponse in un Task. FindAutocompletePredictionsResponse contiene un elenco di oggetti AutocompletePrediction che rappresentano i luoghi previsti. L'elenco potrebbe essere vuoto se non esiste nessun luogo conosciuto corrispondente alla query e ai criteri di filtro.

Per ogni luogo previsto, puoi chiamare i seguenti metodi per recuperare i dettagli del luogo:

• getFullText(CharacterStyle) restituisce il testo completo della descrizione di un luogo. Si tratta di una combinazione di testo primario e secondario. Esempio: "Torre Eiffel, Avenue Anatole France, Parigi, Francia". Inoltre, questo metodo ti consente di evidenziare le sezioni della descrizione che corrispondono alla ricerca con uno stile a tua scelta, utilizzando CharacterStyle. Il parametro CharacterStyle è facoltativo. Impostalo su null se non hai bisogno di evidenziazioni.
• getPrimaryText(CharacterStyle) restituisce il testo principale che descrive un luogo. Di solito si tratta del nome del luogo. Esempi: "Torre Eiffel" e "123 Pitt Street".
• getSecondaryText(CharacterStyle) restituisce il testo secondario di una descrizione del luogo. Questo è utile, ad esempio, come seconda riga quando vengono mostrate le previsioni di completamento automatico. Esempi: "Avenue Anatole France, Parigi, Francia" e "Sydney, Nuovo Galles del Sud".
• getPlaceId() restituisce l'ID luogo del luogo previsto. Un ID luogo è un identificativo text che identifica in modo univoco un luogo e che puoi utilizzare per recuperare di nuovo l'oggetto Place in un secondo momento. Per ulteriori informazioni sugli ID luogo in Places SDK per Android, consulta Place Details. Per informazioni generali sugli ID luogo, consulta la Panoramica degli ID luogo.
• getPlaceTypes() restituisce l'elenco dei tipi di luoghi associati a questo luogo.
• getDistanceMeters() restituisce la distanza in linea retta in metri tra questo luogo e l'origine specificata nella richiesta.

Token di sessione

I token di sessione raggruppano le fasi di query e selezione di una ricerca di completamento automatico dell'utente in una sessione distinta a fini di fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo. Ogni sessione può avere più query, seguite dalla selezione di un luogo. Al termine di una sessione, il token non è più valido; l'app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatico (quando incorpori un frammento o avvii il completamento automatico utilizzando un'intenzione, l'API si occupa di tutto automaticamente).

L'SDK Places per Android utilizza un AutocompleteSessionToken per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione, quindi passare lo stesso token, insieme a un ID luogo, nella chiamata successiva a fetchPlace() per recuperare i dettagli del luogo selezionato dall'utente.

Scopri di più sui token sessione.

Limitare i risultati del completamento automatico

Puoi limitare i risultati di completamento automatico a una regione geografica specifica e/ofiltrare i risultati in base a uno o più tipi di località o a un massimo di cinque paesi. Puoi applicare questi vincoli all'attività di completamento automatico,AutocompleteSupportFragment e alle API di completamento automatico programmatico.

Per limitare i risultati:

• Per preferire i risultati all'interno della regione definita, chiama setLocationBias() (alcuni risultati al di fuori della regione definita potrebbero comunque essere restituiti).
• Per mostrare solo i risultati all'interno della regione definita, chiama setLocationRestriction() (verranno riportati solo i risultati all'interno della regione definita).
• Per restituire solo i risultati conformi a un determinato tipo di luogo, chiama setTypesFilter() (ad esempio, se specifichi TypeFilter.ADDRESS, verranno restituiti solo i risultati con un indirizzo preciso).
• Per restituire solo risultati relativi a un massimo di cinque paesi specificati, chiama setCountries(). I paesi devono essere passati come codice paese compatibile con ISO 3166-1 alpha-2 di due lettere.

Spostare in modo ingiusto i risultati verso una regione specifica

Per orientare i risultati del completamento automatico verso una specifica regione geografica, chiama setLocationBias(), passando un RectangularBounds. L'esempio di codice seguente mostra l'utilizzo di setLocationBias() su un'istanza di frammento per orientare i suggerimenti di completamento automatico a una regione di Sydney, in Australia.

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

      

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

      

Limitare i risultati a una regione specifica

Per limitare i risultati del completamento automatico a una regione geografica specifica, chiama setLocationRestriction(), passando un RectangularBounds. L'esempio di codice seguente mostra l'utilizzo di setLocationRestriction() su un'istanza di frammento per orientare i suggerimenti di completamento automatico a una regione di Sydney, in Australia.

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

      

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

      

Nota: questa limitazione si applica solo a interi percorsi. I risultati sintetici situati al di fuori dei limiti rettangolari possono essere restituiti in base a un percorso che si sovrappone alla limitazione della località.

Filtra i risultati per tipi di luoghi o raccolta di tipi

Puoi limitare i risultati di una richiesta di completamento automatico in modo che restituiscano solo un determinato tipo di luogo. Specifica un filtro utilizzando i tipi di luoghi o una raccolta di tipi elencati nelle tabelle 1, 2 e 3 della pagina Tipi di luoghi. Se non viene specificato nulla, vengono restituiti tutti i tipi.

Per filtrare i risultati di completamento automatico, chiama setTypesFilter() per impostare il filtro.

Per specificare un filtro di tipo o di raccolta di tipi:

• Chiama setTypesFilter() e specifica fino a cinque valori type della Tabella 1 e della Tabella 2 mostrate in Tipi di luoghi. I valori di tipo sono definiti dalle costanti in PlaceTypes.

• Chiama setTypesFilter() e specifica una raccolta di tipi dalla Tabella 3 riportata in Tipi di luoghi. I valori della raccolta sono definiti dalle costanti in PlaceTypes.

  Nella richiesta è consentito un solo tipo della Tabella 3. Se specifichi un valore della Tabella 3, non puoi specificare un valore della Tabella 1 o della Tabella 2. Se lo fai, si verifica un errore.

Il seguente esempio di codice chiama setTypesFilter() su un AutocompleteSupportFragment e specifica più valori di tipo.

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

      

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

      

Il seguente esempio di codice mostra la chiamata a setTypesFilter() su un AutocompleteSupportFragment per impostare un filtro che restituisce solo risultati con un indirizzo preciso specificando una raccolta di tipi.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

Il seguente esempio di codice mostra la chiamata a setTypesFilter() su un IntentBuilder per impostare un filtro che restituisce solo i risultati con un indirizzo preciso specificando una raccolta di tipi.

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

      

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

      

Filtra i risultati per paese

Per filtrare i risultati del completamento automatico fino a cinque paesi, chiama setCountries() per impostare il codice paese. Quindi, passa il filtro a un frammento o a un'intenzione. I paesi devono essere passati come codice paese compatibile con ISO 3166-1 Alpha-2 di due caratteri.

Il seguente esempio di codice mostra l'utilizzo di setCountries() su un AutocompleteSupportFragment per impostare un filtro che restituisce solo risultati all'interno dei paesi specificati.

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

      

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

      

Limiti di utilizzo

L'utilizzo dell'API Places, incluso l'SDK Places per Android, non è più limitato a un numero massimo di richieste al giorno (QPD). Tuttavia, rimangono in vigore i seguenti limiti di utilizzo:

• Il limite di frequenza è 6000 QPM (richieste al minuto). Viene calcolato come somma delle richieste lato client e lato server per tutte le applicazioni che utilizzano le credenziali dello stesso progetto.

Mostrare le attribuzioni nell'app

• Se la tua app utilizza il servizio di completamento automatico in modo programmatico, l'interfaccia utente deve mostrare un'attribuzione "Fornito da Google" o apparire all'interno di una mappa con il brand Google.
• Se la tua app utilizza il widget di completamento automatico, non sono necessarie ulteriori azioni (l'attribuzione richiesta viene visualizzata per impostazione predefinita).
• Se recuperi e mostri ulteriori informazioni sui luoghi dopo aver recuperato un luogo tramite ID, devi anche mostrare gli attributi di terze parti.

Per ulteriori dettagli, consulta la documentazione sulle attribuzioni.

Ottimizzazione del completamento automatico dei luoghi

Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio di completamento automatico dei luoghi.

Ecco alcune linee guida generali:

• Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico dell'API Maps JavaScript, il widget di completamento automatico di Places SDK per Android o il controllo UI di completamento automatico di Places SDK per iOS.
• Acquisisci fin dall'inizio una conoscenza dei campi di dati essenziali di Completamento automatico dei luoghi.
• I campi di bias di località e limitazione della località sono facoltativi, ma possono avere un impatto significativo sul rendimento del completamento automatico.
• Utilizza la gestione degli errori per assicurarti che l'app degradi in modo corretto se l'API restituisce un errore.
• Assicurati che la tua app gestisca la situazione in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget Dettagli dei luoghi e Place Autocomplete per restituire solo i campi dati dei luoghi di cui hai bisogno.

Ottimizzazione avanzata dei costi

Valuta la possibilità di implementare in modo programmatico Place Autocomplete per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. I prezzi per richiesta abbinati all'API Geocoding sono più convenienti rispetto ai prezzi per sessione (in base alla sessione) se sono soddisfatte entrambe le seguenti condizioni:

• Se ti serve solo la latitudine/longitudine o l'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore a una chiamata a Dettagli luogo.
• Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro richieste di previsione di completamento automatico o meno, i prezzi per richiesta potrebbero essere più convenienti rispetto a quelli per sessione.

La tua applicazione richiede altre informazioni oltre all'indirizzo e alla latitudine/longitudine della previsione selezionata?

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Ricerca automatica dei luoghi:

• Aggiungi limitazioni per i paesi, bias di località e (per le implementazioni programmatiche) preferenze di lingua all'implementazione della funzionalità di completamento automatico dei luoghi. Con i widget non è necessaria la preferenza di lingua, poiché le preferenze di lingua vengono scelte dal browser o dal dispositivo mobile dell'utente.
• Se la funzionalità di completamento automatico dei luoghi è accompagnata da una mappa, puoi modificare la posizione in base all'area visibile della mappa.
• Quando un utente non sceglie una delle previsioni del completamento automatico, in genere perché nessuna di queste corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
  • Se prevedi che l'utente inserisca solo i dati dell'indirizzo, riutilizza i dati inseriti dall'utente in una chiamata all'API Geocoding.
  • Se prevedi che l'utente inserisca query per un luogo specifico per nome o indirizzo, utilizza una richiesta di ricerca di luoghi. Se i risultati sono previsti solo in una regione specifica, utilizza la sbiasatura della località.
  Altri scenari in cui è meglio eseguire il fallback all'API Geocoding includono:
  • Utenti che inseriscono indirizzi di proprietà secondarie, ad esempio indirizzi di appartamenti o unità specifiche all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale in Completamento automatico dei luoghi.
  • Utenti che inseriscono indirizzi con prefissi di tratti stradali come "23-30 29th St, Queens" a New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai nelle Hawaii.

Risoluzione dei problemi

Sebbene possano verificarsi una vasta gamma di errori, la maggior parte di quelli che possono verificarsi nella tua app è in genere causata da errori di configurazione (ad esempio, è stata utilizzata la chiave API errata o la chiave API è stata configurata in modo errato) o da errori di quota (la tua app ha superato la quota). Per ulteriori informazioni sulle quote, consulta Limiti di utilizzo.

Gli errori che si verificano durante l'utilizzo dei controlli di completamento automatico vengono restituiti nel callback onActivityResult(). Chiama Autocomplete.getStatus() per ricevere il messaggio di stato relativo al risultato.