Place Autocomplete

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei Servizi. La funzionalità varia in base alla regione. Scopri di più.

Il servizio di completamento automatico in Places SDK per Android restituisce le previsioni 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.
• Ottieni 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. Man mano che 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 Place, che la tua app può utilizzare per ottenere dettagli sul luogo selezionato.

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

• Opzione 1: incorpora un AutocompleteSupportFragment.
• Opzione 2: utilizza un intent 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, annida il frammento all'interno di un altro elemento di layout, ad esempio un CardView.
• Se utilizzi il frammento Autocomplete e devi eseguire l'override di onActivityResult, devi chiamare super.onActivityResult, altrimenti il frammento non funzionerà correttamente.

Aggiungere un PlaceSelectionListener a un'attività

L'elemento 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:

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

      

Opzione 2: utilizza un intent 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 intent.

Nota: questi passaggi non sono necessari se stai incorporando un frammento.

Attenzione: NON avviare AutcompleteActivity direttamente. Utilizza invece un intent per avviare Autocomplete (PlaceAutocomplete nella libreria di compatibilità).

Per avviare il widget di completamento automatico utilizzando un intent:

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

Creare un intent di completamento automatico

L'esempio seguente utilizza Autocomplete.IntentBuilder per creare un intent per avviare il widget di completamento automatico come 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);

      

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

Figura 1: Widget di completamento automatico in modalità OVERLAY

Figura 2: widget di completamento automatico in modalità SCHERMO INTERO

Registrare un callback per il risultato dell'intent

Per ricevere una notifica quando l'utente ha selezionato un luogo, definisci un registerForActivityResult() launcher, che avvia l'attività e gestisce anche il risultato, come mostrato nell'esempio seguente. Se l'utente ha selezionato una previsione, questa verrà fornita nell'intent contenuto nell'oggetto risultato. Poiché l'intent è stato creato da Autocomplete.IntentBuilder, il metodo Autocomplete.getPlaceFromIntent() può estrarre l'oggetto 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");
            }
        });

      

Ottenere previsioni sui luoghi in modo programmatico

Puoi creare una UI di ricerca personalizzata in alternativa alla UI fornita dal widget di completamento automatico. Per farlo, la tua app deve ottenere le previsioni dei luoghi in modo programmatico. La tua app può ottenere un elenco di nomi di luoghi e/o indirizzi previsti dall'API Autocomplete chiamando PlacesClient.findAutocompletePredictions(), passando un oggetto FindAutocompletePredictionsRequest con i seguenti parametri:

• Obbligatorio:una stringa query contenente il testo digitato dall'utente.
• Consigliato: A AutocompleteSessionToken, che raggruppa le fasi di query e selezione di una ricerca utente in una sessione discreta ai fini della 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 di due lettere (ISO 3166-1 Alpha-2), che indicano il paese o i paesi a cui devono essere limitati i risultati.

• (Facoltativo) Un 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 eliminare l'ambiguità dei 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 specificato in modo completo.
  • 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 posizione 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().

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

      

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 un luogo noto 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 del testo principale 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 evidenziazione.
• getPrimaryText(CharacterStyle) restituisce il testo principale che descrive un luogo. Di solito si tratta del nome del luogo. Esempi: "Torre Eiffel" e "Via Roma, 123".
• 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 identificatore testuale che identifica in modo univoco un luogo, che puoi utilizzare per recuperare l'oggetto Place in un secondo momento. Per ulteriori informazioni sugli ID luogo in Places SDK per Android, consulta Dettagli luogo. Per informazioni generali sugli ID luogo, consulta la panoramica dell'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.

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, consulta Inizializzare il client dell'API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una delle classi di richieste (ad esempio, FetchPlaceRequest). L'annullamento viene eseguito in base al criterio del "best effort". Una volta emessa una richiesta di annullamento, non verrà restituita alcuna risposta. L'emissione di un token di annullamento NON garantisce che una determinata richiesta verrà annullata e potresti comunque ricevere un addebito per la richiesta anche se non viene restituita alcuna risposta.

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 discreta ai fini della 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 da una selezione di un luogo. Una volta terminata una sessione, il token non è più valido e la tua app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatiche (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occupa automaticamente).

Places SDK for Android utilizza un AutocompleteSessionToken per identificare ogni sessione. La tua 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.

Suggerimento :se la tua app utilizza il widget di completamento automatico, non devi implementare le sessioni, in quanto il widget le gestisce automaticamente in background.

Scopri di più sui token di sessione.

Limitare i risultati del completamento automatico

Puoi limitare i risultati del completamento automatico a una regione geografica specifica e/o filtrarli in base a uno o più tipi di luoghi oppure 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 dare la priorità ai risultati all'interno della regione definita, chiama setLocationBias() (alcuni risultati provenienti da fuori della regione definita potrebbero comunque essere restituiti).
• Per mostrare solo i risultati all'interno della regione definita, chiama setLocationRestriction() (verranno restituiti 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 i risultati all'interno di un massimo di cinque paesi specificati, chiama setCountries(). I paesi devono essere trasmessi come codice paese compatibile con ISO 3166-1 alpha-2 di due caratteri.

Orientare i risultati verso una regione specifica

Per dare priorità ai risultati del completamento automatico per una specifica regione geografica, chiama setLocationBias(), passando un RectangularBounds. Il seguente esempio di codice mostra la chiamata di setLocationBias() su un'istanza di frammento per orientare i suggerimenti di completamento automatico verso una regione di Sydney, in 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)));

      

Limitare i risultati a una regione specifica

Per limitare i risultati del completamento automatico a una regione geografica specifica, chiama setLocationRestriction(), passando un RectangularBounds. Il seguente esempio di codice mostra la chiamata di setLocationRestriction() su un'istanza di frammento per orientare i suggerimenti di completamento automatico verso una regione di Sydney, in 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: questa limitazione viene applicata solo a interi itinerari. I risultati sintetici che si trovano al di fuori dei limiti rettangolari possono essere restituiti in base a un itinerario 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 luogo o una raccolta di tipi elencati nelle tabelle 1, 2 e 3 in Tipi di luogo. Se non viene specificato nulla, vengono restituiti tutti i tipi.

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

Per specificare un filtro per tipo o raccolta di tipi:

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

• Chiama setTypesFilter() e specifica una raccolta di tipi dalla Tabella 3 mostrata 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 dalla Tabella 3, non puoi specificare un valore dalla Tabella 1 o dalla Tabella 2. In questo caso, si verifica un errore.

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

Kotlin

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

      

Java

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

      

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

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

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

      

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

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

      

Filtrare i risultati per paese

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

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

Kotlin

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

      

Java

    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, si applicano ancora i seguenti limiti di utilizzo:

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

Visualizzare le attribuzioni nell'app

• Se la tua app utilizza il servizio di completamento automatico a livello di programmazione, la tua UI deve visualizzare un'attribuzione "Powered by Google" o apparire all'interno di una mappa con il brand Google.
• Se la tua app utilizza il widget di completamento automatico, non è necessaria alcuna azione aggiuntiva (l'attribuzione richiesta viene visualizzata per impostazione predefinita).
• Se recuperi e visualizzi informazioni aggiuntive sul luogo dopo aver ottenuto un luogo per ID, devi visualizzare anche le attribuzioni di terze parti.

Per ulteriori dettagli, consulta la documentazione relativa alle attribuzioni.

Ottimizzazione di Place Autocomplete (legacy)

Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete (legacy).

Ecco alcune linee guida generali:

• Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget Place Autocomplete (legacy) dell'API Maps JavaScript, il widget Place Autocomplete (legacy) di Places SDK for Android o il controllo UI Place Autocomplete (legacy) di Places SDK for iOS.
• Sviluppa una comprensione dei campi di dati essenziali di Place Autocomplete (legacy) fin dall'inizio.
• I campi di distorsione della località e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
• Utilizza la gestione degli errori per assicurarti che la tua app funzioni correttamente se l'API restituisce un errore.
• Assicurati che la tua app gestisca i casi in cui non è presente alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione di base dei costi

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

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica di Place Autocomplete (legacy) per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding sul luogo selezionato anziché su Place Details (legacy). Il prezzo per richiesta abbinato all'API Geocoding è più conveniente del prezzo per sessione (basato sulla sessione) se vengono soddisfatte entrambe le seguenti condizioni:

• Se hai bisogno solo della latitudine/longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata a Place Details (legacy).
• Se gli utenti selezionano un suggerimento di completamento automatico entro una media di quattro o meno richieste di completamento automatico di Places (legacy), il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.

Per assistenza nella scelta dell'implementazione di Place Autocomplete (legacy) più adatta alle tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.

La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?

Sì, sono necessari ulteriori dettagli

Utilizza il completamento automatico dei luoghi basato sulla sessione (legacy) con Places Details (legacy).
Poiché la tua applicazione richiede Place Details (legacy) come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Place Autocomplete (legacy) deve utilizzare un token di sessione (a livello di programmazione o integrato nei widget JavaScript, Android o iOS). per sessione più gli SKU di dati di Places applicabili a seconda dei campi di dati del luogo che richiedi.¹

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete (legacy) sia la richiesta Place Details (legacy) nella previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi dati del luogo di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete (legacy). Quando richiedi Dettagli luogo (legacy) sulla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo dalla risposta di Place Autocomplete (legacy)
2. Il token di sessione utilizzato nella richiesta Place Autocomplete (legacy)
3. Il parametro fields che specifica i campi di dati del luogo di cui hai bisogno

No, servono solo l'indirizzo e la posizione

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (legacy) per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete (legacy). L'efficienza di Place Autocomplete (legacy) di ogni applicazione varia a seconda di ciò che inseriscono gli utenti, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione del rendimento.

Per rispondere alla seguente domanda, analizza il numero medio di caratteri digitati da un utente prima di selezionare una previsione di completamento automatico di Place (legacy) nella tua applicazione.

In media, gli utenti selezionano una previsione di completamento automatico di Places (legacy) in quattro o meno richieste?

Sì

Implementa Place Autocomplete (legacy) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionato.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'invio di quattro richieste Place Autocomplete (legacy) - Per Request più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato costa meno di Place Autocomplete (legacy) - Per Session per sessione.¹

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano in un numero ancora minore di caratteri.

No

Utilizza il completamento automatico dei luoghi basato sulla sessione (legacy) con Places Details (legacy).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Place Autocomplete (legacy) supera il costo dei prezzi per sessione, l'implementazione di Place Autocomplete (legacy) deve utilizzare un token di sessione sia per le richieste Place Autocomplete (legacy) sia per la richiesta Place Details (legacy) associata per sessione.¹

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete (legacy) sia la richiesta Place Details (legacy) nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi Dati di base.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete (legacy). Quando richiedi Dettagli luogo (legacy) sulla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo dalla risposta di Place Autocomplete (legacy)
2. Il token di sessione utilizzato nella richiesta Place Autocomplete (legacy)
3. Il parametro fields che specifica i campi Dati di base come indirizzo e geometria

Valuta la possibilità di ritardare le richieste di completamento automatico di Places (legacy)
Puoi utilizzare strategie come il ritardo di una richiesta di completamento automatico di Places (legacy) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione effettui meno richieste. Ad esempio, effettuare richieste di completamento automatico di Places (legacy) per ogni carattere dopo che l'utente ha digitato il terzo carattere significa che se l'utente digita sette caratteri e seleziona una previsione per la quale effettui una richiesta dell'API Geocoding, il costo totale sarà per 4 completamenti automatici di Places (legacy) per richiesta + geocodifica.¹

Se il ritardo delle richieste può portare la tua richiesta programmatica media al di sotto di quattro, puoi seguire le indicazioni per l'implementazione di Place Autocomplete (legacy) con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere le previsioni a ogni nuovo tasto premuto.

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero inferiore di caratteri.

---

1. Per i costi, consulta i listini prezzi di Google Maps Platform.

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Place Autocomplete (legacy):

• Aggiungi limitazioni per paese, priorità alla località, e (per le implementazioni programmatiche) preferenza della lingua all'implementazione di Place Autocomplete (legacy). La preferenza della lingua non è necessaria con i widget, poiché questi scelgono le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
• Se Place Autocomplete (legacy) è accompagnato da una mappa, puoi impostare la posizione in base all'area visibile della mappa.
• Nelle situazioni in cui un utente non sceglie una delle previsioni di Place Autocomplete (legacy), in genere perché nessuna di queste previsioni corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input originale dell'utente per tentare di ottenere risultati più pertinenti:
  • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
  • Se prevedi che l'utente inserisca query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo (legacy). Se i risultati sono previsti solo in una regione specifica, utilizza l'aggiustamento della località.
  Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
  • Gli utenti che inseriscono indirizzi di locali secondari, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" restituisce una previsione parziale in Place Autocomplete (legacy).
  • Utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai nelle Hawaii.

Risoluzione dei problemi

Sebbene possa verificarsi un'ampia gamma di errori, la maggior parte di quelli che la tua app potrebbe riscontrare sono in genere causati 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 per il risultato.