Place Autocomplete

Seleziona la piattaforma: Android iOS JavaScript Web Service

Il servizio di completamento automatico in Places SDK per Android restituisce il luogo previsioni in risposta alle query di ricerca degli utenti. Mentre l'utente digita, il servizio di completamento automatico restituisce suggerimenti per luoghi quali attività, indirizzi, plus code e punti d'interesse.

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

Aggiungere un widget di completamento automatico

Il widget di completamento automatico è una finestra di dialogo di ricerca con completamento automatico integrato funzionalità. 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 visualizzata una Place che viene restituita, che la tua app può utilizzare per ottenere dettagli luogo selezionato.

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

Opzione 1: incorpora un elemento AutocompleteSupportFragment

Per aggiungere AutocompleteSupportFragment alla tua app:

  1. Aggiungi un frammento al layout XML della tua 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 bordo 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à

L'elemento PlaceSelectionListener gestisce la restituzione di un luogo in risposta alla richiesta dell'utente selezione. 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'intenzione.

Per avviare il widget di completamento automatico utilizzando un intent:

  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 intent di completamento automatico

L'esempio riportato di seguito utilizza Autocomplete.IntentBuilder per creare un intent e 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 in overlay o a schermo intero. I seguenti screenshot mostrano modalità di visualizzazione:

Quando visualizzato in modalità overlay, il widget di completamento automatico appare sovrapposto all&#39;interfaccia utente di chiamata.
Figura 1: widget di completamento automatico in modalità SOVRAPOSIZIONE
Quando viene visualizzato in modalità a schermo intero, il widget di completamento automatico riempie l&#39;intero schermo.
Figura 2: widget di completamento automatico in modalità a schermo intero

Registra un callback per il risultato dell'intent

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

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

Ricevere previsioni sui luoghi in modo programmatico

Puoi creare un'interfaccia utente di ricerca personalizzata come alternativa a quella fornita dal widget di completamento automatico. A tale scopo, l'app deve ricevere previsioni sui luoghi in modo programmatico. 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: una o più lettere del paese codici (ISO 3166-1 Alpha-2), che indica il paese o i paesi a cui devono essere visualizzati i risultati limitato.

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

    • 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 di completamento automatico con un all'indirizzo preciso. Utilizza questo tipo quando sai che l'utente sta cercando un indirizzo completamente specificato.
    • TypeFilter.ESTABLISHMENT: restituisce solo i luoghi che sono aziendali.

    • 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 che corrispondono 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) dal 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 nessun luogo conosciuto corrispondente alla query e ai criteri di filtro.

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

  • getFullText(CharacterStyle) restituisce il testo completo della descrizione di un luogo. Si tratta di una combinazione principale e secondario. Esempio: "Torre Eiffel, Avenue Anatole France, Parigi, Francia". Inoltre, questo metodo ti consente di evidenziare le sezioni del descrizione che corrisponda alla ricerca con uno stile di tua scelta, utilizzando CharacterStyle Il parametro CharacterStyle è facoltativo. In caso contrario, impostalo su null. che richiedono un'evidenziazione.
  • getPrimaryText(CharacterStyle) restituisce il testo principale che descrive un luogo. Si tratta solitamente del nome del posto. Esempi: "Torre Eiffel" e "123 Pitt Street".
  • getSecondaryText(CharacterStyle) restituisce il testo della società controllata della descrizione di un luogo. Questo è utile per Ad esempio, come seconda riga quando mostri 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. L'ID luogo è una stringa che identifica in modo univoco un luogo, che puoi utilizzare per recuperare il Place di nuovo in seguito. Per ulteriori informazioni sugli ID luogo in SDK Places per Android, consulta Place Dettagli. Per informazioni generali sugli ID luogo, consulta la Panoramica degli ID luogo.
  • getPlaceTypes() restituisce l'elenco dei tipi di luogo associati al 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 del completamento automatico di un utente eseguire ricerche 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 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).

Places SDK per Android utilizza un oggetto 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.

Limita risultati di completamento automatico

Puoi limitare i risultati del completamento automatico a una regione geografica specifica e/o filtra i risultati per uno o più tipi di luogo o per un massimo di cinque paesi. Tu puoi applicare questi vincoli all'attività di completamento automatico AutocompleteSupportFragment e le API di completamento automatico della pubblicità programmatica.

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 risultati conformi a un determinato tipo di luogo, chiama setTypesFilter() (ad esempio, se specifichi TypeFilter.ADDRESS restituirà i risultati risultati solo con un indirizzo preciso).
  • Per restituire solo risultati entro un massimo di cinque paesi specificati, chiama setCountries(). I paesi devono essere trasmessi con un formato ISO 3166-1 a due caratteri Paese compatibile con Alpha-2 Google Cloud.

Risultati bias per una regione specifica

Per differenziare i risultati del completamento automatico in base a una regione geografica specifica, chiama setLocationBias(), ha superato un RectangularBounds L'esempio di codice seguente mostra la chiamata a setLocationBias() su un frammento per polarizzare i suoi suggerimenti di completamento automatico in base a 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(), ha superato un RectangularBounds L'esempio di codice seguente mostra la chiamata a setLocationRestriction() su un un'istanza di frammento per polarizzare i suggerimenti di completamento automatico in una regione di Sydney, 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 si applica solo a interi percorsi e a risultati sintetici situate all'esterno dei limiti rettangolari possono essere restituiti in base a una route si sovrappone alla limitazione di località.

Filtra i risultati per tipi di luogo o raccolta dei 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 tipo o un filtro per la raccolta dei 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 dei tipi dalla tabella 3 mostrata nella sezione Tipi di luogo. I valori della raccolta sono definiti 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 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 a setTypesFilter() su un AutocompleteSupportFragment per impostare un filtro che restituisce solo 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));

L'esempio di codice seguente mostra la chiamata a setTypesFilter() su un IntentBuilder per impostare un filtro che restituisca solo risultati con un indirizzo preciso in base a per specificare una raccolta dei 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);

Filtra i risultati per paese

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

L'esempio di codice seguente mostra la chiamata a setCountries() su un AutocompleteSupportFragment, per impostare un filtro che restituisca solo risultati all'interno delle nei 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, rimangono validi i seguenti limiti di utilizzo:

  • Il limite di frequenza è di 6000 QPM (richieste al minuto). È calcolata come somma delle richieste lato client e lato server per tutte delle applicazioni che usano 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 mostrano un link "Powered by Google" attribuzione o apparire all'interno di un 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 visualizzi ulteriori informazioni sul luogo dopo aver ricevuto un posto per ID, devono mostrare anche attribuzioni 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 ottenere il massimo Servizio Place Autocomplete.

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare Widget di completamento automatico dell'API Maps JavaScript, Widget di completamento automatico dell'SDK Places per Android, o Places SDK per iOS Controllo UI con completamento automatico
  • Acquisisci fin dall'inizio una conoscenza dei campi di dati essenziali per il completamento automatico dei luoghi.
  • I campi della differenziazione per località e delle restrizioni di località sono facoltativi ma possono hanno un impatto significativo sulle prestazioni 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 di Place Autocomplete utilizza le maschere dei campi nei widget Place Details e Place Autocomplete per restituire solo campi di dati del luogo necessari.

Ottimizzazione avanzata dei costi

Prendi in considerazione l'implementazione programmatica di Place Autocomplete per accedere ai prezzi per richiesta e richiedere risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. Il prezzo Per richiesta abbinato all'API Geocoding è più conveniente rispetto al prezzo Per sessione (basato su 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 Place Details.
  • 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.
Per assistenza nella scelta dell'implementazione di Completamento automatico dei luoghi più adatta alle tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.

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

Sì, sono necessari ulteriori dettagli

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

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Questo include sia le richieste Place Autocomplete sia la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi dati dei luoghi di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi i dettagli dei luoghi relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta di Place Autocomplete
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. Il parametro fields che specifica i campi di dati dei luoghi di cui hai bisogno

No, sono necessari solo indirizzo e posizione

L'API Geocoding potrebbe essere un'opzione più conveniente di Dettagli dei luoghi per la tua applicazione, a seconda del rendimento dell'utilizzo di Completamento automatico dei luoghi. L'efficienza del completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti accedono, di dove viene utilizzata l'applicazione e dell'implementazione o meno di best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza il numero di caratteri digitati in media da un utente prima di selezionare una previsione di Place Autocomplete nella tua applicazione.

In media, i tuoi utenti selezionano una previsione del completamento automatico dei luoghi in quattro o meno richieste?

Sì

Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionata.
L'API Geocoding invia indirizzi e coordinate di latitudine/longitudine a 0,005 $per richiesta. L'invio di quattro richieste Place Autocomplete - Per richiesta costa 0,01132 $, pertanto il costo totale di quattro richieste più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è pari a 0,01632 $, inferiore al prezzo di 0,017 $ per sessione di Autocomplete per sessione.1

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

No

Utilizza la funzionalità di completamento automatico dei luoghi basata sulla sessione con i dettagli dei luoghi.
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione Place Autocomplete supera il costo del prezzo Per sessione, l'implementazione di Place Autocomplete deve utilizzare un token di sessione sia per le richieste Place Autocomplete sia per la richiesta Place Details associata per un costo totale di 0,017 $per sessione.1

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Questo include sia le richieste Place Autocomplete sia la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields per avere la certezza di richiedere solo i campi Dati di base.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi i dettagli del luogo relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta di Place Autocomplete.
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  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 dei luoghi
Puoi utilizzare strategie come il ritardo di una richiesta di completamento automatico dei luoghi fino a quando l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione effettui meno richieste. Ad esempio, se effettui richieste di completamento automatico dei luoghi 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 all'API Geocoding, il costo totale sarà di 0,01632 $ (4 * 0,00283 $ per completamento automatico per richiesta + 0,005 $ per geocodifica).1

Se il ritardo delle richieste può ridurre la richiesta programmatica media a meno di quattro, puoi seguire le indicazioni per l'implementazione di Autocompletamento dei luoghi efficiente con l'API Geocoding. Tieni presente che le richieste ritardate possono essere percepite come latenza dall'utente che potrebbe aspettarsi di vedere le previsioni a ogni nuova sequenza di tasti.

Valuta la possibilità di adottare le best practice sul rendimento per consentire agli utenti di ottenere la previsione che cercano con meno caratteri.

  1. I costi indicati qui sono in dollari statunitensi. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.

Best practice per le prestazioni

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

  • Aggiungi limitazioni in base al paese. differenziazione per località, e (per le implementazioni di pubblicità programmatica) la preferenza della lingua per Place Autocomplete implementazione. La preferenza della lingua non è necessaria con widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se Place Autocomplete è accompagnato da una mappa, puoi differenziare 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 differenziazione per località.
    Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
    • Utenti che inseriscono indirizzi di locali secondari nei paesi in cui Place Autocomplete supporta gli indirizzi secondari sono incompleti, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale in Posizione completamento automatico.
    • Utenti che inseriscono indirizzi con prefissi di segmenti di strada come "23-30 29th St, Queens" nel New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai, alle Hawaii.

Risoluzione dei problemi

Può verificarsi un'ampia varietà di errori, ma nella maggior parte dei casi la tua app che si verificano sono generalmente causati da errori di configurazione (ad esempio, è stata utilizzata una chiave API errata o la chiave API è stata configurata in modo errato) oppure la quota (la tua app ha superato la quota disponibile). 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 tag Chiamata di onActivityResult(). Chiama Autocomplete.getStatus() per ricevere il messaggio di stato relativo al risultato.