Il servizio di completamento automatico dell'SDK Places per Android restituisce previsioni dei luoghi in risposta alle query di ricerca degli utenti. Man mano che 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:
- Aggiungi un widget di completamento automatico per risparmiare tempo nello sviluppo e garantire un'esperienza utente coerente.
- Ricevi previsioni 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. Mentre 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 può essere utilizzata dall'app per ottenere dettagli sul
luogo selezionato.
Sono disponibili due opzioni per aggiungere il widget di completamento automatico alla tua app:
- Opzione 1: incorpora un elemento
AutocompleteSupportFragment. - Opzione 2: utilizza un intent per avviare l'attività di completamento automatico.
Opzione 1: incorpora un AutocompleteSupportFragment
Per aggiungere un elemento AutocompleteSupportFragment alla tua app:
- Aggiungi un frammento al layout XML dell'attività.
- 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 CardView.
- Se utilizzi il frammento Autocomplete e devi eseguire l'override di
onActivityResult, devi chiamaresuper.onActivityResult, altrimenti il frammento non funzionerà correttamente.
Aggiunta di PlaceSelectionListener a un'attività
L'elemento PlaceSelectionListener gestisce la restituzione di un luogo in risposta alla selezione
da parte dell'utente. Il codice seguente mostra la creazione di un riferimento al frammento e l'aggiunta di un listener a 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), può avviare il completamento automatico utilizzando un intent.
Per avviare il widget di completamento automatico utilizzando un intent:
- Utilizza
Autocomplete.IntentBuilderper creare un intent, passando la modalitàAutocompletedesiderata. - Definisci un'utilità di avvio dei risultati di attività
registerForActivityResultche possa essere utilizzata per avviare l'intent e gestire la previsione del luogo selezionato dall'utente nel risultato.
Creare un intent di completamento automatico
L'esempio seguente utilizza
Autocomplete.IntentBuilder
per creare un intent per avviare il widget di completamento automatico come intent:
Kotlin
// Set the fields to specify which types of place data to
// return after the user has made a selection.
val fields = listOf(Place.Field.ID, Place.Field.NAME)
// Start the autocomplete intent.
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this)
startAutocomplete.launch(intent)
Java
// Set the fields to specify which types of place data to
// return after the user has made a selection.
List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
// Start the autocomplete intent.
Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this);
startAutocomplete.launch(intent);
Quando utilizzi un intent per avviare il widget di completamento automatico, puoi scegliere tra le modalità di visualizzazione overlay o a schermo intero. Gli screenshot seguenti mostrano rispettivamente tutte le modalità di visualizzazione:
Registra un callback per il risultato dell'intent
Per ricevere una notifica quando l'utente ha selezionato un luogo, definisci un Avvio app registerForActivityResult(), che avvia l'attività e gestisce anche il risultato come mostrato nell'esempio seguente. Se l'utente ha selezionato una previsione, questa verrà pubblicata nell'intent contenuto nell'oggetto risultato. Poiché l'intent
è stato creato da Autocomplete.IntentBuilder, il metodo
Autocomplete.getPlaceFromIntent() può estrarre da quest'ultimo l'oggetto Place.
Kotlin
private val startAutocomplete =
registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
if (result.resultCode == Activity.RESULT_OK) {
val intent = result.data
if (intent != null) {
val place = Autocomplete.getPlaceFromIntent(intent)
Log.i(
TAG, "Place: ${place.name}, ${place.id}"
)
}
} else if (result.resultCode == Activity.RESULT_CANCELED) {
// The user canceled the operation.
Log.i(TAG, "User canceled autocomplete")
}
}
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
new ActivityResultContracts.StartActivityForResult(),
result -> {
if (result.getResultCode() == Activity.RESULT_OK) {
Intent intent = result.getData();
if (intent != null) {
Place place = Autocomplete.getPlaceFromIntent(intent);
Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
}
} else if (result.getResultCode() == Activity.RESULT_CANCELED) {
// The user canceled the operation.
Log.i(TAG, "User canceled autocomplete");
}
});
Ottenere le previsioni in modo programmatico
Puoi creare un'interfaccia utente di ricerca personalizzata in alternativa a quella fornita dal widget di completamento automatico. A questo scopo, l'app deve ricevere le previsioni delle posizioni 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(), trasmettendo 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 della ricerca di un 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 applicare i risultati.
(Facoltativo) Un
TypeFilter, che puoi utilizzare per limitare i risultati al tipo di luogo specificato. Sono supportati i seguenti tipi di luogo:TypeFilter.GEOCODE- Restituisce solo risultati di geocodifica, anziché dati relativi ad attività commerciali. Utilizza questa richiesta per distinguere i risultati in cui la località specificata potrebbe essere indeterminata.TypeFilter.ADDRESS- Restituisce solo i risultati del completamento automatico con un indirizzo preciso. Utilizza questo tipo quando sai che l'utente sta cercando un indirizzo completamente specificato.TypeFilter.ESTABLISHMENT- Restituisce solo luoghi che sono attività commerciali.TypeFilter.REGIONS- Restituisce solo luoghi che corrispondono a uno dei seguenti tipi:LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES– Restituisce solo i risultati che corrispondono 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 luogo, consulta la guida ai tipi di luogo.
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. Il campo FindAutocompletePredictionsResponse
contiene un elenco di oggetti
AutocompletePrediction
che rappresentano i luoghi previsti. L'elenco può essere vuoto, se non esiste una posizione nota corrispondente alla query e ai criteri di filtro.
Per ogni luogo previsto, puoi chiamare i seguenti metodi per recuperare i dettagli sul luogo:
getFullText(CharacterStyle)restituisce il testo completo della descrizione di un luogo. Questa è una combinazione di testo principale e secondario. Esempio: "Torre Eiffel, Avenue Anatole France, Parigi, Francia". Inoltre, questo metodo consente di evidenziare le sezioni della descrizione che corrispondono alla ricerca con uno stile di tua scelta utilizzandoCharacterStyle. Il parametroCharacterStyleè facoltativo. Impostalo su null se non è necessaria l'evidenziazione.getPrimaryText(CharacterStyle)restituisce il testo principale che descrive un luogo. Di solito si tratta del nome del luogo. Esempi: "Torre Eiffel" e "Via 123 Pitt".getSecondaryText(CharacterStyle)restituisce il testo della società controllata di una descrizione del luogo. Questo è utile, ad esempio, come seconda riga quando vengono mostrate le previsioni di completamento automatico. Esempi: "Anatole France, Parigi, 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 di nuovo l'oggettoPlacein un secondo momento. Per ulteriori informazioni sugli ID luogo nell'SDK Places per Android, consulta la sezione Dettagli luogo. Per informazioni generali sugli ID luogo, consulta la panoramica ID luogo.getPlaceTypes()restituisce l'elenco dei tipi di luogo associati a questo luogo.getDistanceMeters()restituisce la distanza in metri retta tra questo luogo e l'origine specificata nella richiesta.
Token di sessione
I token di sessione raggruppano le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo. Ogni sessione può includere più query, seguite da una selezione di luoghi. Al termine di una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico di pubblicità programmatica (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occuperà automaticamente).
L'SDK Places per Android utilizza un elemento
AutocompleteSessionToken
per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione, quindi trasmettere lo stesso token, insieme a un ID luogo, nella successiva chiamata a fetchPlace() per recuperare i Dettagli luogo relativi al luogo selezionato dall'utente.
Scopri di più sui token di sessione.
Limita risultati di completamento automatico
Puoi limitare i risultati del completamento automatico a un'area geografica specifica e/o
filtrarli per uno o più tipi di luogo o per 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 preferisci i risultati all'interno della regione definita, chiama
setLocationBias()(alcuni risultati al di fuori della regione definita potrebbero comunque essere restituiti). - Per mostrare i risultati solo all'interno della regione definita, chiama
setLocationRestriction()(verranno restituiti solo i risultati all'interno della regione definita). - Per restituire solo risultati conformi a un determinato tipo di luogo, chiama
setTypesFilter()(ad esempio, se specifichiTypeFilter.ADDRESSverranno restituiti solo risultati con un indirizzo preciso). - Per restituire solo i risultati in un massimo di cinque paesi specificati, chiama il numero
setCountries(). I paesi devono essere trasmessi come codice paese a due caratteri compatibile con lo standard ISO 3166-1 Alpha-2.
Risultati della pregiudizio per una regione specifica
Per differenziare i risultati del completamento automatico in base a una regione geografica specifica, chiama
setLocationBias(), passando un
RectangularBounds.
L'esempio di codice seguente mostra una chiamata a setLocationBias() su un'istanza di frammento per differenziare i suggerimenti di completamento automatico in 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)));
Limita i risultati a una regione specifica
Per limitare i risultati del completamento automatico a una regione geografica specifica, chiama
setLocationRestriction(), trasmettendo un
RectangularBounds.
Il seguente esempio di codice mostra una chiamata a setLocationRestriction() su un'istanza di frammento per differenziare i suggerimenti di completamento automatico in una regione di Sydney, in Australia.
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
Nota: questa limitazione viene applicata solo a intere route; i risultati sintetici al di fuori dei confini rettangolari potrebbero essere restituiti in base a una route che 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 luogo o una raccolta dei tipi elencati nelle tabelle 1, 2 e 3 in Tipi di luogo. Se non viene specificato nulla, vengono restituiti tutti i tipi.
Per filtrare i risultati del completamento automatico, chiama
setTypesFilter()
per impostare il filtro.
Per specificare un tipo o un filtro per la raccolta del tipo:
Richiama
setTypesFilter()e specifica fino a cinque valori type della Tabella 1 e della Tabella 2 mostrati in Tipi di luogo. I valori di tipo sono definiti dalle costanti in PlaceTypes.Richiama
setTypesFilter()e specifica una raccolta dei tipi dalla Tabella 3 mostrata 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 dalla 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.
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
L'esempio di codice seguente mostra una chiamata a setTypesFilter() su un
AutocompleteSupportFragment per impostare un filtro che restituisce solo risultati con un
indirizzo preciso specificando una raccolta dei tipi.
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
L'esempio di codice seguente mostra una chiamata a setTypesFilter() su un
IntentBuilder per impostare un filtro che restituisce solo risultati con un indirizzo preciso
specificando una raccolta di tipi.
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(PlaceTypes.ADDRESS))
.build(this)
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.build(this);
Filtra i risultati per paese
Per filtrare i risultati del completamento automatico in base a un massimo di cinque paesi, chiama il numero
setCountries()
per impostare il codice paese.
Quindi, passa il filtro a un frammento o a un intent. I paesi devono essere trasmessi come codice paese a due caratteri compatibile con lo standard ISO 3166-1 Alpha-2.
L'esempio di codice seguente mostra una chiamata a setCountries() su un
AutocompleteSupportFragment, per impostare un filtro che restituisce solo risultati all'interno dei
paesi specificati.
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Java
autocompleteFragment.setCountries("AU", "NZ");
Limiti di utilizzo
Il tuo utilizzo dell'API Places, incluso l'SDK Places per Android, non è più limitato a un numero massimo di richieste al giorno (QPD). Tuttavia, si applicano ancora i seguenti limiti di utilizzo:
- Il limite di frequenza è 6000 QPM (richieste al minuto). Questo valore viene calcolato come somma delle richieste lato client e lato server per tutte le applicazioni che utilizzano le credenziali dello stesso progetto.
Attribuzioni della Rete Display nell'app
- Se la tua app utilizza il servizio di completamento automatico in modo programmatico, l'interfaccia utente deve mostrare l'attribuzione "Powered by Google" o comparire all'interno di una mappa con brand Google.
- Se la tua app utilizza il widget di completamento automatico, non sono richieste ulteriori azioni (l'attribuzione obbligatoria viene visualizzata per impostazione predefinita).
- Se recuperi e mostri informazioni aggiuntive sui luoghi dopo aver ottenuto un luogo in base all'ID, devi mostrare anche le 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 utilizzare al meglio il servizio Place Autocomplete.
Di seguito sono riportate alcune linee guida generali:
- Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico dell'API Maps JavaScript, il widget di completamento automatico dell'SDK Places per Android o il controllo dell'interfaccia utente di completamento automatico dell'SDK Places per iOS.
- Sviluppa una comprensione dei campi di dati essenziali di Place Autocomplete sin dall'inizio.
- I campi relativi alla differenziazione per località e alla limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
- Utilizza la gestione degli errori per assicurarti che la tua app venga ridotta correttamente se l'API restituisce un errore.
- Assicurati che la tua app gestisca quando non c'è selezione e offra agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere di campo nei widget Place Details e Place Autocomplete per restituire solo i campi dei dati dei luoghi necessari.
Ottimizzazione dei costi avanzata
Prendi in considerazione l'implementazione programmatica di Place Autocomplete per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. I prezzi Per richiesta abbinati all'API Geocoding sono più convenienti rispetto ai prezzi Per sessione (basati 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 per meno di una chiamata Place Details.
- Se gli utenti selezionano una previsione di completamento automatico in una media di quattro richieste di previsioni di completamento automatico o meno, i prezzi per richiesta potrebbero essere più convenienti rispetto a quelli per sessione.
La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?
Sì, sono necessari ulteriori dettagli
Utilizza Place Autocomplete basato sulla sessione con Place Details.
Poiché la tua applicazione richiede Place Details, 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 (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di $0, 017 per sessione oltre agli SKU di dati di Places applicabili in base ai campi di dati dei luoghi richiesti{/14.
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete sia la richiesta Place Details sulla previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi dei dati del luogo necessari.
Implementazione programmatica
Utilizza un token sessione con le richieste di Place Autocomplete. Quando richiedi Place Details per la previsione selezionata, includi i seguenti parametri:
- L'ID luogo dalla risposta Place Autocomplete
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fieldsche specifica i campi dati dei luoghi necessari
No, richiede solo indirizzo e posizione
L'API Geocoding potrebbe essere un'opzione più economica rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza di completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti stanno inserendo, dove l'applicazione è in uso e se sono state implementate best practice per l'ottimizzazione delle prestazioni.
Per rispondere alla seguente domanda, analizza il numero di caratteri che un utente digita in media prima di selezionare una previsione di Place Autocomplete nella tua applicazione.
I tuoi utenti selezionano una previsione di Place Autocomplete in una media di quattro o meno richieste?
Sì
Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding nella previsione della posizione selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine al costo di 0,005 $per richiesta. Effettuare quattro richieste Place Autocomplete - Per Request costa $0,01132, quindi il costo totale di quattro richieste più una chiamata API Geocoding per la previsione del luogo selezionata sarebbe di $0,01632, che è inferiore al prezzo del completamento automatico per sessione di $0,017 per sessione.1
Valuta la possibilità di adottare best practice per il rendimento per aiutare gli utenti a ottenere le previsioni che cercano con ancora meno caratteri.
No
Utilizza Place Autocomplete basato sulla sessione con Place Details.
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Place Autocomplete supera il costo dei prezzi per sessione, la tua 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 dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete sia la richiesta Place Details sulla 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 sessione con le richieste di Place Autocomplete. Quando richiedi Place Details per la previsione selezionata, includi i seguenti parametri:
- L'ID luogo dalla risposta Place Autocomplete
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fieldsche specifica i campi Dati di base, come l'indirizzo e la geometria
Valuta la possibilità di ritardare le richieste di Place Autocomplete
Puoi utilizzare strategie come il ritardo di una richiesta Place Autocomplete finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se l'utente effettua una richiesta di Place Autocomplete per ogni carattere dopo che l'utente ha digitato il terzo carattere, significa che se l'utente digita sette caratteri seleziona una previsione per la quale effettui una richiesta all'API Geocoding, il costo totale sarà di $0,01632 (4 * $0,00283 Autocomplete per richiesta + $0,005 Geocoding).1
Se con un ritardo le richieste la tua richiesta di pubblicità programmatica media risulta inferiore a quattro, puoi seguire le indicazioni per l'implementazione di Place Autocomplete con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza da parte dell'utente, il quale potrebbe aspettarsi di vedere le previsioni a ogni nuova sequenza di tasti.
Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere le previsioni che cercano con meno caratteri.
-
I costi elencati qui sono espressi 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 le prestazioni del completamento automatico di Place:
- Aggiungi restrizioni in base al paese, differenziazione per località e (per le implementazioni programmatiche) preferenze linguistiche all'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria per i widget, perché questi ultimi scelgono la lingua dal browser o dal dispositivo mobile dell'utente.
- Se Place Autocomplete è accompagnato da una mappa, puoi differenziare la posizione in base alla visualizzazione della mappa.
- Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico, in genere perché nessuna di queste previsioni rappresenta l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per cercare 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 per nome o indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in una regione specifica, utilizza la differenziazione per località.
- Utenti che inseriscono indirizzi secondari in paesi in cui il supporto di Place Autocomplete per gli indirizzi secondari è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" fornisce una previsione parziale in Place Autocomplete.
- Gli utenti inseriscono gli indirizzi con prefissi del tratto di strada, ad esempio "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.
Risolvere i problemi
Sebbene possa verificarsi un'ampia gamma di errori, la maggior parte degli errori che si possono verificare con l'app sono in genere causati da errori di configurazione (ad esempio, è stata utilizzata la chiave API sbagliata o la chiave API è stata configurata in modo errato) o errori di quota (l'app ha superato la quota). Consulta Limiti di utilizzo per ulteriori informazioni sulle quote.
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.