Place Autocomplete

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.
Seleziona piattaforma: Android iOS JavaScript Servizio web

Il servizio di completamento automatico nell'SDK Places per Android restituisce le previsioni dei luoghi in risposta alle query di ricerca degli utenti. Durante la digitazione, il servizio di completamento automatico restituisce suggerimenti relativi a luoghi quali attività commerciali, 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 completamento automatico è una finestra di dialogo di ricerca con funzionalità di completamento automatico integrate. Quando un utente inserisce 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

Per aggiungere AutocompleteSupportFragment all'app:

  1. Aggiungi un frammento al layout XML della tua attività.
  2. Aggiungi un listener alla tua attività o al tuo 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 CardView.
  • Se utilizzi il frammento di completamento automatico e devi sostituire onActivityResult, devi chiamare super.onActivityResult, altrimenti il frammento non funzionerà correttamente.

Aggiungere un PlaceSelectionListener a un'attività

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

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

      

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

      

Opzione 2: utilizza un intent per lanciare 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), l'app può avviare il completamento automatico utilizzando un intent.

Per avviare il widget completamento automatico utilizzando un intent, segui questi passaggi:

  1. Utilizza Autocomplete.IntentBuilder per creare un intent, passando la modalità Autocomplete desiderata. L'intent deve chiamare startActivityForResult, trasmettendo un codice di richiesta che identifica l'intent.
  2. Esegui l'override del callback onActivityResult per ricevere il luogo selezionato.

Creare un intent di completamento automatico

L'esempio seguente mostra come utilizzare Autocomplete.IntentBuilder per creare un intent per lanciare il widget completamento automatico come intent:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

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

Sostituisci il callback onActivityResult

Per ricevere una notifica quando l'utente ha selezionato un luogo, l'app deve sostituire il onActivityResult() dell'attività, controllando il codice di richiesta che hai passato per il tuo intent, come mostrato nell'esempio seguente.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Generare previsioni del luogo in modo programmatico

Puoi creare un'UI di ricerca personalizzata come alternativa all'UI fornita dal widget completamento automatico. Per farlo, la tua app deve ricevere le previsioni sui luoghi in modo programmatico. L'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:una 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 si conclude quando seleziona un luogo.
  • Consigliati: un RectangularBounds oggetto, che specifica i limiti di latitudine e longitudine per limitare i risultati alla regione specificata.
  • Facoltativo: una o più codici paese (ISO 3166-1 Alpha-2) di due lettere, che indicano il paese o i paesi a cui i risultati devono essere limitati.
  • Facoltativo:una 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 disambiguare i risultati in cui la località specificata può essere indeterminata.
    • TypeFilter.ADDRESS: restituisce solo risultati di completamento automatico con un indirizzo preciso. Utilizza questo tipo se 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 che corrispondono 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 luogo, consulta la guida ai tipi di luogo.

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

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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

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(TypeFilter.ADDRESS.toString()))
            .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)
            }
        }

      

L'API restituisce un FindAutocompletePredictionsResponse in una 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 del 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 Francia, Parigi, Francia". Inoltre, questo metodo ti consente di evidenziare le sezioni della descrizione che corrispondono alla ricerca con uno stile a tua scelta usando CharacterStyle. Il parametro CharacterStyle è facoltativo. Impostalo su null se non hai bisogno di evidenziare.
  • getPrimaryText(CharacterStyle) restituisce il testo principale che descrive un luogo. Di solito si tratta del nome del luogo. Esempi: "Torre Eiffel" e "Via Pitt 123".
  • getSecondaryText(CharacterStyle) restituisce il testo secondario della descrizione di un luogo. Questo dato è utile, ad esempio, come seconda riga quando vengono visualizzate le previsioni del completamento automatico. Esempi: "Avenue Anatole France, Paris, Francia" e "Sydney, Nuovo Galles del Sud".
  • getPlaceId() restituisce l'ID del luogo previsto. Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo, che puoi utilizzare per recuperare nuovamente l'oggetto Place. Per scoprire di più sugli ID luogo nell'SDK Places per Android, consulta i dettagli del luogo. Per informazioni generali sugli ID luogo, consulta la panoramica sull'ID luogo.
  • getPlaceTypes() restituisce l'elenco dei tipi di luogo associati.
  • 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 con completamento automatico dell'utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e si conclude quando seleziona un luogo. Ogni sessione può avere più query, seguite da una selezione di un luogo. Una volta conclusa 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 intent, l'API si occupa di questo automaticamente).

L'SDK Places per Android utilizza una AutocompleteSessionToken per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione e poi trasmettere 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 di sessione.

Limita i risultati di completamento automatico

Puoi limitare i risultati di completamento automatico a un'area geografica specifica e/o filtrare i risultati per uno o più tipi di luogo o fino a cinque paesi. Puoi applicare questi vincoli all'attività di completamento automatico, AutocompleteSupportFragment e alle API di completamento automatico programmatico.

Per limitare i risultati, procedi come segue:

  • Per preferire i risultati all'interno dell'area geografica definita, chiama setLocationBias() (alcuni risultati provenienti dall'esterno dell'area geografica definita potrebbero comunque essere restituiti).
  • Per mostrare solo i risultati all'interno dell'area geografica definita, chiama setLocationRestriction() (verranno restituiti solo risultati all'interno dell'area geografica).
  • Per restituire solo risultati che corrispondono a un determinato tipo di luogo, chiama setTypesFilter() (ad esempio, se specifichi TypeFilter.ADDRESS, restituisci solo risultati con un indirizzo preciso).
  • Per restituire solo risultati entro un massimo di cinque paesi specificati, chiama il numero setCountries(). I paesi devono essere trasmessi come codice paese compatibile con ISO 3166-1 Alpha-2 a due caratteri.

Differenziazione dei risultati per un'area geografica specifica

Per biasing i risultati del completamento automatico a un'area geografica specifica, chiama setLocationBias(), passando un RectangularBounds. Il seguente esempio di codice mostra la chiamata a setLocationBias() su un'istanza di frammento per indirizzare i suoi suggerimenti di completamento automatico a un'area geografica di Sydney, in Australia.

Java


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

      

Kotlin


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

      

Limita i risultati a un'area geografica specifica

Per limitare i risultati di completamento automatico a un'area geografica specifica, chiama setLocationRestriction(), passando un RectangularBounds. L'esempio di codice riportato di seguito mostra la chiamata a setLocationRestriction() su un'istanza di frammento per indirizzare i suoi suggerimenti di completamento automatico a un'area geografica di Sydney, in Australia.

Java


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

      

Kotlin


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

      

Nota: questa restrizione si applica solo a interi percorsi. I risultati sintetici che si trovano al di fuori dei confini rettangolari possono essere restituiti in base a un percorso che si sovrappone con il limite di località.

Filtrare i risultati per tipo di luogo o raccolta di tipi

Puoi limitare i risultati da 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 è specificato nulla, vengono restituiti tutti i tipi.

Per filtrare i risultati del 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 tra quelli della Tabella 1 e della Tabella 2 visualizzati nei Tipi di luogo. I valori dei tipi sono definiti dalle costanti in PlaceTypes.

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

    Nella richiesta è consentito un solo tipo dalla tabella 3. Se specifichi un valore nella Tabella 3, non puoi specificarne uno 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.

Java


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

      

Kotlin


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

      

L'esempio di codice riportato di seguito mostra la chiamata a setTypesFilter() su un AutocompleteSupportFragment per impostare un filtro che restituisce solo i risultati con un indirizzo esatto specificando una raccolta di tipi.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

L'esempio di codice seguente 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.

Java


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

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Filtra 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 frammento o intento. I paesi devono essere trasmessi come codice paese compatibile con ISO 3166-1 Alpha-2 a due caratteri.

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

Java


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

      

Kotlin


    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 i seguenti limiti di utilizzo:

  • Il limite di frequenza è di 100 richieste al secondo (QPS). Viene calcolata sommando le richieste lato client e lato server per tutte le applicazioni che utilizzano le credenziali dello stesso progetto.

Attribuzioni display nell'app

  • Se la tua app utilizza il servizio di completamento automatico in modo programmatico, l'interfaccia utente deve mostrare un'attribuzione "Con tecnologia di Google" o apparire all'interno di una mappa con brand Google.
  • Se la tua app utilizza il widget di completamento automatico non è richiesta alcuna azione aggiuntiva (l'attribuzione richiesta viene visualizzata per impostazione predefinita).
  • Se recuperi e mostri informazioni aggiuntive sul luogo dopo aver acquistato un luogo tramite ID, devi visualizzare anche le attribuzioni di terze parti.

Per ulteriori dettagli, consulta la documentazione sulle attribuzione.

Effettua l'ottimizzazione con completamento automatico

Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio di completamento automatico dei luoghi.

Di seguito sono riportate alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare l'API Maps JavaScript widget di completamento automatico, il widget di completamento automatico di Places SDK for Android o il controllo dell'UI di completamento automatico di Places
  • Sviluppa una comprensione dei campi dati di completamento automatico del luogo dall'inizio.
  • I campi di geolocalizzazione e di limitazione della posizione sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che l'app venga ridotta correttamente se l'API restituisce un errore.
  • Assicurati che la tua app gestisca quando non è presente alcuna selezione e offre 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 di completamento automatico del luogo, utilizza le maschere dei campi nei widget Dettagli luogo e Completa automaticamente per restituire solo i campi dati dei luoghi necessari.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica del completamento automatico del luogo per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding sul luogo selezionato anziché sul luogo. I prezzi per richiesta abbinati all'API Geocoding sono più economici rispetto ai prezzi per sessione (basati su sessione) se vengono soddisfatte entrambe le seguenti condizioni:

  • Se hai solo bisogno della latitudine/longitudine o dell'indirizzo del luogo selezionato dell'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata Dettagli luogo.
  • Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro richieste di previsione di completamento automatico o meno, il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.
Per assistenza nella selezione dell'implementazione del completamento automatico dei luoghi che soddisfa le 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 con i dettagli del luogo.
Poiché la tua applicazione richiede dettagli sul luogo, come il nome, lo stato dell'attività o l'orario di apertura, l'implementazione del completamento automatico del luogo deve utilizzare un token sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di $0, 017 per sessione più SKU di dati di Places in base a quali campi di dati di un luogo richiedi.

Implementazione dei widget
La gestione delle sessioni viene integrata automaticamente nei widget
JavaScript, Android o iOS. Sono incluse sia le richieste di completamento automatico di luogo sia le richieste di dettagli sui luoghi nella 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 di completamento automatico dei luoghi. Quando richiedi Dettagli luogo sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta al completamento automatico del luogo
  2. Il token di sessione utilizzato nella richiesta di completamento automatico del luogo.
  3. Il parametro fields che specifica i campi di dati dei luoghi necessari

No, sono necessari soltanto l'indirizzo e la località

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza del completamento automatico di ogni applicazione varia in base al dispositivo utilizzato dagli utenti, al luogo in cui viene utilizzata e all'implementazione delle best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza il numero di caratteri digitato da un utente in media prima di selezionare una previsione di completamento automatico del luogo nella tua applicazione.

In media, gli utenti selezionano una previsione di completamento automatico di luogo in un massimo di quattro richieste?

Implementa il completamento automatico dei luoghi in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine per 0,005 $per richiesta. Effettuando quattro richieste di completamento automatico per richiesta, costa 0,01132 $, quindi il costo totale di quattro richieste più una chiamata API di geocodifica sulla previsione di luogo selezionata sarà di 0,01632 $, che è inferiore al prezzo di completamento automatico per sessione di 0,017 $per sessione.1

Valuta la possibilità di utilizzare best practice relative alle prestazioni per aiutare gli utenti a ottenere la previsione che cercano in un numero di caratteri inferiore.

No

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

Implementazione dei widget
La gestione delle sessioni viene integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste di completamento automatico di luogo sia le richieste di dettagli sui luoghi 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 di completamento automatico dei luoghi. Quando richiedi Dettagli luogo sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta al completamento automatico del luogo
  2. Il token di sessione utilizzato nella richiesta di completamento automatico del luogo.
  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 un luogo
Puoi utilizzare strategie quali il ritardo di una richiesta di completamento automatico del luogo finché l'utente non ha digitato i primi tre o quattro caratteri in modo che l'applicazione effettui meno richieste. Ad esempio, inoltrando le richieste di Completamento automatico di ciascun carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale si esegue una richiesta API Geocoding, il costo totale sarà pari a $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1

Se le richieste in ritardo possono raggiungere una media di richieste di pubblicità programmatica inferiore a quattro, puoi seguire le istruzioni per l'implementazione del completamento automatico dei luoghi con l'API Geocoding. Tieni presente che le richieste in ritardo possono essere percepite come latenza dall'utente e questo può aspettarsi di vedere previsioni a ogni nuova pressione dei tasti.

Valuta la possibilità di utilizzare best practice relative alle prestazioni per aiutare gli utenti a ottenere la previsione che cercano in meno caratteri.


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

Best practice per il rendimento

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento del completamento automatico dei luoghi:

  • Aggiungi le limitazioni in base al paese, la polizza di località e (per le implementazioni programmatiche) la preferenza di lingua all'implementazione del completamento automatico dei luoghi. La preferenza della lingua non è necessaria con i widget perché selezionano le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico del luogo è accompagnato da una mappa, puoi orientare la posizione in base al viewport della mappa.
  • Nei casi in cui un utente non scelga una delle previsioni del completamento automatico, in genere dato che nessuna di queste previsioni corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente inserirà solo le informazioni sull'indirizzo, riutilizza l'input utente originale durante una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserirà query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in un'area geografica specifica, utilizza la differenziazione dei luoghi.
    Altri scenari in cui è preferibile utilizzare l'API Geocoding:
    • Utenti che inseriscono indirizzi di premesse in paesi diversi da Australia, Nuova Zelanda o Canada. Ad esempio, l'indirizzo statunitense "123 Bowdoin St #456, Boston MA, USA" non è supportato dal completamento automatico. (il completamento automatico supporta indirizzi di premesse solo in Australia, Nuova Zelanda e Canada). I formati degli indirizzi supportati in questi tre paesi includono "9/321 Pitt Street, Sydney, New South Wales, Australia" o "14/19 Langana Avenue, Browns Bay, Auckland, Nuova Zelanda" o "145-112 Renfrew Dr, Markham, Ontario, Canada").
    • Gli utenti che inseriscono indirizzi con prefissi del tratto di strada, come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" nell'isola di Kauai nell'Hawai'i.

Risoluzione dei problemi

Anche se è possibile che si verifichi un'ampia varietà di errori, la maggior parte degli errori probabilmente riscontrati dall'app sono causati da errori di configurazione (ad esempio, è stata utilizzata la chiave API errata o la chiave API è stata configurata in modo errato) o errori di quota (l'app ha superato la quota). Consulta i limiti di utilizzo per ulteriori informazioni sulle quote.

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