Place Autocomplete (Legacy) 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 l'uniformità dell'esperienza utente.
- Ottieni previsioni sui luoghi in modo programmatico per creare un'esperienza utente personalizzata.
Aggiungi un widget di completamento automatico
Il widget di completamento automatico è una finestra di dialogo di ricerca con funzionalità di completamento automatico integrata. Quando un utente inserisce i termini di ricerca, il widget presenta un elenco di luoghi previsti tra cui scegliere. Quando l'utente effettua una selezione, viene restituita un'istanza Place, che l'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, segui questi passaggi:
- Aggiungi un frammento al layout XML dell'attività.
- Aggiungi un listener all'attività o al frammento.
Aggiungi AutocompleteSupportFragment a un'attività
Per aggiungere AutocompleteSupportFragment a un'attività, aggiungi un nuovo frammento a un layout XML. Ad esempio:
<fragment android:id="@+id/autocomplete_fragment"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
/>
- Per impostazione predefinita, il frammento non ha bordi o sfondo. Per fornire un aspetto visivo coerente, nidifica il frammento all'interno di un altro elemento di layout, ad esempio un CardView.
- Se utilizzi il frammento di completamento automatico e devi eseguire l'override di
onActivityResult, devi chiamaresuper.onActivityResult, altrimenti il frammento non funzionerà correttamente.
Aggiungi 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
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. val basicAutocompleteIntent = BasicPlaceAutocomplete.createIntent(this) { setCountries(listOf("AU", "NZ")) }
Java
// Build a BasicPlaceAutocomplete intent to allow the user to select a place. Intent basicAutocompleteIntent = new BasicPlaceAutocomplete.IntentBuilder() .setCountries(List.of("AU", "NZ")) .build(this);
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), l'app può avviare il completamento automatico utilizzando un intent.
Per avviare il widget di completamento automatico utilizzando un intent, segui questi passaggi:
- Utilizza
Autocomplete.IntentBuilderper creare un intent, passando la modalitàAutocompletedesiderata. - Definisci un programma di avvio dei risultati dell'attività
registerForActivityResultche può essere utilizzato per avviare l'intent e gestire la previsione del luogo selezionato dall'utente nel risultato.
Crea 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
val intent = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) } startAutocomplete.launch(intent)
Java
// Start the autocomplete intent. Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .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 ciascuna modalità di visualizzazione:
Registra un callback per il risultato dell'intent
Per ricevere una notifica quando l'utente ha selezionato un luogo, definisci un
launcher registerForActivityResult(), che avvia l'attività e gestisce anche il
risultato, come mostrato nell'esempio seguente. Se l'utente ha selezionato una previsione, questa verrà inviata nell'intent contenuto nell'oggetto del risultato. Poiché l'intent è stato creato da Autocomplete.IntentBuilder, il metodo Autocomplete.getPlaceFromIntent() può estrarre l'oggetto Place.
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == RESULT_OK) { val intent = result.data if (intent != null) { val prediction = PlaceAutocomplete.getPredictionFromIntent(intent) if (prediction != null) { binding.autocompleteResult.text = getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.placeId, prediction.getSecondaryText(null), ) Log.i( TAG, "Place: ${prediction.getPrimaryText(null)}, ${prediction.placeId}", ) } } } else if (result.resultCode == RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete) Log.i(TAG, "User canceled autocomplete") } else if (result.resultCode == PlacesSdkAutocompleteActivity.RESULT_ERROR) { val intent = result.data if (intent != null) { val status = PlaceAutocomplete.getResultStatusFromIntent(intent) Log.e(TAG, "An error occurred: ${status?.statusMessage}") } } }
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); if (prediction != null) { binding.autocompleteResult.setText( getString( R.string.place_selection, prediction.getPrimaryText(null), prediction.getPlaceId(), prediction.getSecondaryText(null))); Log.i( TAG, "Place: " + prediction.getPrimaryText(null) + ", " + prediction.getPlaceId()); } } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. binding.autocompleteResult.setText(R.string.user_canceled_autocomplete); Log.i(TAG, "User canceled autocomplete"); } else if (result.getResultCode() == com.google.android.libraries.places.widget .PlaceAutocompleteActivity.RESULT_ERROR) { Intent intent = result.getData(); if (intent != null) { Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); if (status != null) { Log.e(TAG, "An error occurred: " + status.getStatusMessage()); } } } });
Ottenere previsioni sui luoghi in modo programmatico
Puoi creare una UI di ricerca personalizzata in alternativa a quella fornita dal widget di completamento automatico. Per farlo, l'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() e passando un oggetto FindAutocompletePredictionsRequest con i seguenti parametri:
- Obbligatorio: una stringa
querycontenente il testo digitato dall'utente. - Consigliato: un
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 completamente specificato.TypeFilter.ESTABLISHMENT: restituisce solo i luoghi che sono attività.TypeFilter.REGIONS: restituisce solo i luoghi che corrispondono a uno dei seguenti tipi:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES: restituisce solo i risultati corrispondenti aLOCALITYoADMINISTRATIVE_AREA_LEVEL_3.
Facoltativo: un
LatLngche specifica la località di origine della richiesta. Quando chiamisetOrigin(), 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.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build() placesClient.findAutocompletePredictions(request) .addOnSuccessListener { response: FindAutocompletePredictionsResponse -> val builder = StringBuilder() for (prediction in response.autocompletePredictions) { builder.append(prediction.getPrimaryText(null).toString()).append("\n") Log.i(TAG, prediction.placeId) Log.i(TAG, prediction.getPrimaryText(null).toString()) } binding.autocompleteResult.text = builder.toString() }.addOnFailureListener { exception: Exception? -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message) } }
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(List.of(PlaceTypes.ESTABLISHMENT)) .setSessionToken(token) .setQuery(query) .build(); placesClient .findAutocompletePredictions(request) .addOnSuccessListener( (response) -> { StringBuilder builder = new StringBuilder(); for (AutocompletePrediction prediction : response.getAutocompletePredictions()) { builder.append(prediction.getPrimaryText(null).toString()) .append("\n"); Log.i(TAG, prediction.getPlaceId()); Log.i(TAG, prediction.getPrimaryText(null).toString()); } binding.autocompleteResult.setText(builder.toString()); }) .addOnFailureListener( (exception) -> { if (exception instanceof ApiException apiException) { Log.e(TAG, "Place not found: " + apiException.getStatusCode()); binding.autocompleteResult.setText( getString( R.string.place_not_found, apiException.getMessage())); } });
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, utilizzandoCharacterStyle. Il parametroCharacterStyleè facoltativo. Impostalo su null se non hai bisogno di evidenziazioni.getPrimaryText(CharacterStyle)restituisce il testo principale che descrive un luogo. In genere si tratta del nome del luogo. Esempi: "Torre Eiffel" e "123 Pitt Street".getSecondaryText(CharacterStyle)restituisce il testo secondario della descrizione di un 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 e che puoi utilizzare per recuperare l'oggettoPlacein un secondo momento. Per saperne di più sugli ID luogo in Places SDK for Android, consulta Dettagli dei luoghi. Per informazioni generali sugli ID luogo, consulta la panoramica degli ID luogo.getPlaceTypes()restituisce l'elenco dei tipi di luogo associati a questo luogo.getDistanceMeters()restituisce la distanza in linea retta in metri tra questo luogo e l'origine specificata nella richiesta.
Token di sessione
I token di sessione raggruppano le fasi di query e selezione di una ricerca con completamento automatico dell'utente in una sessione distinta 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. 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 se ne occupa automaticamente).
L'SDK Places per Android utilizza un
AutocompleteSessionToken
per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione, quindi passare lo stesso token, insieme a un ID luogo, nella chiamata successiva a fetchPlace() per recuperare i dettagli del luogo selezionato dall'utente.
Scopri di più sui token di sessione.
Limita i risultati del completamento automatico
Puoi limitare i risultati del completamento automatico a una regione geografica specifica e/o filtrare i risultati in base a uno o più tipi di luoghi o a un massimo di cinque paesi. Puoi
applicare questi vincoli all'attività di completamento automatico,
AutocompleteSupportFragment e alle API di completamento automatico programmatico.
Per limitare i risultati:
- Per dare la preferenza ai risultati all'interno della regione definita, chiama
setLocationBias()(potrebbero comunque essere restituiti alcuni risultati esterni alla regione definita). - 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 specifichiTypeFilter.ADDRESS, verranno restituiti solo i risultati con un indirizzo preciso). - Per restituire solo i risultati relativi a un massimo di cinque paesi specificati, chiama
setCountries(). I paesi devono essere trasmessi come codice paese di due caratteri compatibile con lo standard ISO 3166-1 Alpha-2.
Influenzare i risultati in base a una regione specifica
Per influenzare i risultati del completamento automatico in base a un'area geografica specifica, chiama setLocationBias(), passando un RectangularBounds.
L'esempio di codice seguente mostra la chiamata di setLocationBias() su un'istanza di frammento per dare priorità ai suggerimenti di completamento automatico per un'area di Sydney, in Australia.
Kotlin
intentBuilder.setLocationBias(bounds)
Java
intentBuilder.setLocationBias( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
Limita i risultati a una regione specifica
Per limitare i risultati del completamento automatico a un'area geografica specifica, chiama setLocationRestriction(), passando un RectangularBounds.
Il seguente esempio di codice mostra la chiamata di setLocationRestriction() su un'istanza di frammento per dare priorità ai suggerimenti di completamento automatico per un'area di Sydney, in Australia.
Kotlin
intentBuilder.setLocationRestriction(bounds)
Java
intentBuilder.setLocationRestriction( RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
Nota: questa limitazione viene applicata solo a interi percorsi. I risultati sintetici situati al di fuori dei limiti rettangolari possono essere restituiti in base a un percorso che si sovrappone alla limitazione della località.
Filtra i risultati per tipi di luoghi o raccolta di tipi
Puoi limitare i risultati di una richiesta di completamento automatico in modo che restituiscano solo un determinato tipo di luogo. Specifica un filtro utilizzando i tipi di luoghi o una raccolta di tipi elencati nelle tabelle 1, 2 e 3 in Tipi di luoghi. 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 dalla Tabella 1 e dalla Tabella 2 mostrate in Tipi di luoghi. I valori del tipo sono definiti dalle costanti inPlaceTypes.Chiama
setTypesFilter()e specifica una raccolta di tipi dalla Tabella 3 mostrata in Tipi di luoghi. I valori della raccolta sono definiti dalle costanti inPlaceTypes.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. In caso contrario, si verifica un errore.
Il seguente esempio di codice chiama setTypesFilter() su un
AutocompleteSupportFragment e specifica più valori di tipo.
Kotlin
intentBuilder.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
intentBuilder.setTypesFilter(List.of("landmark", "restaurant", "store"));
L'esempio di codice seguente 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
intentBuilder.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
intentBuilder.setTypesFilter(List.of(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 = PlaceAutocomplete.createIntent(this) { setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT)) }
Java
Intent intent = new PlaceAutocomplete.IntentBuilder() .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT)) .build(this);
Filtra i risultati per paese
Per filtrare i risultati del completamento automatico in un massimo di cinque paesi, chiama
setCountries()
per impostare il codice paese.
Poi, passa il filtro a un frammento o a un intent. I paesi devono essere trasmessi come codice paese di due caratteri compatibile con lo standard ISO 3166-1 Alpha-2.
L'esempio di codice seguente mostra la chiamata di setCountries() su un AutocompleteSupportFragment per impostare un filtro che restituisce solo i risultati all'interno dei paesi specificati.
Kotlin
intentBuilder.setCountries(listOf("AU", "NZ"))
Java
intentBuilder.setCountries(List.of("AU", "NZ"));
Limiti di utilizzo
L'utilizzo dell'API Places (Legacy), incluso Places SDK for Android (Legacy), non è più limitato a un numero massimo di richieste al giorno (QPD). Tuttavia, si applicano comunque 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.
Visualizza le attribuzioni nella tua app
- Se la tua app utilizza il servizio di completamento automatico in modo programmatico, la tua UI deve mostrare 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 è richiesta alcuna azione aggiuntiva (l'attribuzione richiesta viene visualizzata per impostazione predefinita).
- Se recuperi e mostri informazioni aggiuntive sui luoghi dopo aver recuperato un luogo tramite ID, devi mostrare anche le attribuzioni di terze parti.
Per maggiori dettagli, consulta la documentazione sulle 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.
- Comprendi i campi di dati essenziali di Place Autocomplete (Legacy) fin dall'inizio.
- I campi di polarizzazione 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 l'app si degradi correttamente se l'API restituisce un errore.
- Assicurati che la tua app gestisca i casi 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 di utilizzo del servizio Place Autocomplete (Legacy), utilizza le maschere di campo nei widget Place Details (Legacy) e Place Autocomplete (Legacy) per restituire solo i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno.
Ottimizzazione avanzata dei costi
Valuta l'implementazione programmatica di Place Autocomplete (Legacy) per accedere ai prezzi di SKU: Autocomplete - Per Request e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (Legacy). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:
- Se hai bisogno solo della latitudine e della 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 (Legacy).
- Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di Place Autocomplete (Legacy), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.
La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?
Sì, servono altri dettagli
Utilizza Place Autocomplete (Legacy) basato su sessione con Place 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 (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione più gli SKU di dati di Places applicabili, a seconda dei campi di dati dei luoghi richiesti.1
Implementazione dei 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) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno.
Implementazione programmatica
Utilizza un
token di sessione
con le tue richieste Place Autocomplete (Legacy). Quando richiedi i dettagli dei luoghi (legacy) relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Place Autocomplete (Legacy)
- Il token di sessione utilizzato nella richiesta Place Autocomplete (Legacy)
- Il parametro
fieldsche specifica i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno
No, sono necessari 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 di utilizzo di Place Autocomplete (Legacy). L'efficienza di Place Autocomplete (Legacy) di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione delle prestazioni.
Per rispondere alla seguente domanda, analizza quanti caratteri digita in media un utente prima di selezionare una previsione di Place Autocomplete (Legacy) nella tua applicazione.
Sì
Implementa Place Autocomplete (Legacy) 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.
L'esecuzione di quattro richieste Autocomplete - Per Request più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è inferiore al costo per sessione di Place Autocomplete (Legacy).1
Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora minore di caratteri.
No
Utilizza Place Autocomplete (Legacy) basato su sessione con Place 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, la tua 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.
1
Implementazione dei 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) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di cui hai bisogno.
Implementazione programmatica
Utilizza un
token di sessione
con le tue richieste Place Autocomplete (Legacy).
Quando richiedi i dettagli dei luoghi (legacy) relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Place Autocomplete (Legacy)
- Il token di sessione utilizzato nella richiesta Place Autocomplete (Legacy)
- Il parametro
fieldsche specifica i campi di dati Basic Data, come indirizzo e geometria
Valuta la possibilità di ritardare le richieste di Place Autocomplete (Legacy)
Puoi adottare strategie come ritardare una richiesta di Place Autocomplete (Legacy) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se effettui richieste di Place Autocomplete (Legacy) per ogni carattere dopo che l'utente ha digitato il terzo carattere, significa che se l'utente digita sette caratteri e poi seleziona una previsione per la quale effettui una richiesta API Geocoding, il costo totale sarà di 4 richieste Place Autocomplete (Legacy) Per Request + Geocoding.1
Se ritardando le richieste puoi ridurre la media delle richieste programmatiche a meno 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 nuova pressione di un tasto.
Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con meno caratteri.
-
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 le prestazioni di Place Autocomplete (Legacy):
- Aggiungi limitazioni in base al paese, località preferita e (per le implementazioni programmatiche) preferenza sulla lingua all'implementazione di Place Autocomplete (Legacy). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
- Se Place Autocomplete (Legacy) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
- In situazioni in cui un utente non sceglie una delle previsioni di Place Autocomplete (Legacy), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale 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 Place Details (Legacy). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
- Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" genera 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 alle Hawaii.
Bias di località
Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Place Autocomplete (Legacy) preferisce mostrare i risultati
all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.
Limitazione della località
Limita i risultati a un'area specificata passando un parametro locationRestriction.
Puoi anche limitare i risultati alla regione definita da location
e da un parametro radius aggiungendo il parametro
strictbounds
. In questo modo, Place Autocomplete (Legacy) restituisce solo i risultati all'interno di quella regione.
Risoluzione dei problemi
Sebbene possano verificarsi molti tipi di errori, la maggior parte degli errori che la tua app potrebbe riscontrare è solitamente causata da errori di configurazione (ad esempio, è stata utilizzata una 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 saperne di più 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.