Autocomplete (New) restituisce previsioni relative ai luoghi in risposta a una richiesta che include una stringa di ricerca testuale e limiti geografici che controllano l'area di ricerca. Il completamento automatico può trovare corrispondenze con parole intere e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e Plus Code. La tua applicazione può inviare query mentre l'utente digita, per fornire previsioni di luoghi e query in tempo reale.
Ad esempio, chiami Autocomplete utilizzando come input una stringa che contiene un input utente parziale, "Sicilian piz", con l'area di ricerca limitata a San Francisco, in California. La risposta contiene quindi un elenco di previsioni di luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, ad esempio il ristorante denominato "Sicilian Pizza Kitchen". Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo desiderato. Puoi effettuare una richiesta Place Details (New) per ottenere maggiori informazioni su una qualsiasi delle previsioni dei luoghi restituite.
Puoi integrare la funzionalità di completamento automatico (nuovo) nella tua app in due modi principali:
- Aggiungi il widget Place Autocomplete: fornisce un'esperienza di completamento automatico della ricerca pronta all'uso tramite la classe
PlaceAutocomplete, che mostra le previsioni man mano che l'utente digita. - Ottieni previsioni sui luoghi in modo programmatico: chiama l'API direttamente per recuperare le previsioni e visualizzarle in un'interfaccia utente personalizzata.
Aggiungi il widget Place Autocomplete
Per offrire più facilmente un'esperienza di completamento automatico dei luoghi coerente, puoi aggiungere il widget Place Autocomplete alla tua app. Il widget fornisce un'interfaccia dedicata a schermo intero che gestisce l'input dell'utente e mostra le previsioni dei luoghi all'utente, restituendo al contempo oggetti AutocompletePrediction all'app. Puoi quindi effettuare una richiesta Place Details (New) per ottenere ulteriori informazioni su una qualsiasi delle previsioni dei luoghi.
Come quando ottieni le previsioni sui luoghi in modo programmatico,
il widget Place Autocomplete ti consente di utilizzare i token di sessione per
raggruppare le richieste di completamento automatico in una sessione ai fini della fatturazione. Puoi passare un token di sessione durante la creazione dell'intent per il widget chiamando setAutocompleteSessionToken(). Se non fornisci un token di sessione, il widget ne creerà uno per te, a cui puoi accedere chiamando getSessionTokenFromIntent(). Per ulteriori informazioni sull'utilizzo dei token di sessione, consulta
Informazioni sui token di sessione.
Per aggiungere il widget Place Autocomplete alla tua app:
(Facoltativo) Definisci un token di sessione. Se non fornisci un token di sessione, il widget ne creerà uno per te.
Definisci un
autocompleteIntentcon i parametri desiderati e il token di sessione.Definisci un
ActivityResultLauncherperStartActivityForResult. Questo launcher gestirà il risultato restituito dall'attività di completamento automatico.Gestisci il risultato nel callback di
ActivityResultLauncher. Ciò comporta l'estrazione diAutocompletePredictioneAutocompleteSessionToken(se non hai fornito i tuoi), la gestione degli errori e, facoltativamente, l'invio di una richiestafetchPlace()per ottenere ulteriori dettagli su un luogo.Avvia l'intent utilizzando
placeAutocompleteActivityResultLauncher
I seguenti esempi mostrano come aggiungere il widget Place Autocomplete utilizzando sia Kotlin che Java:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
Personalizza il tema
Quando crei un'istanza di un'esperienza di completamento automatico, puoi specificare un tema che sostituisce uno qualsiasi degli attributi di stile predefiniti. Puoi personalizzare i colori, la tipografia, la spaziatura, i bordi e gli angoli del componente Place Autocomplete. Il valore predefinito è PlacesMaterialTheme. Tutti gli attributi del tema che non vengono sostituiti utilizzano gli stili predefiniti.
Puoi definire gli override del tema in …/res/values/themes.xml. Ad esempio:
<?xml version="1.0" encoding="utf-8"?> <resources> <style name="BrandedTheme" parent="PlacesMaterialTheme"> <!-- Color tokens. --> <item name="placesColorOnNeutralContainer">#5300e8</item> <item name="placesColorOnNeutralContainerVariant">#ee6002</item> ... <!-- Typography tokens. --> <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item> <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item> ... <!-- Spacing tokens. --> <item name="placesSpacingSmall">6dp</item> <item name="placesSpacingMedium">12dp</item> ... <!-- Attribution tokens. --> <item name="placesColorAttributionLightTheme">white</item> <item name="placesColorAttributionDarkTheme">black</item> </style> </resources>
Puoi quindi fare riferimento agli stili di override chiamando setAutocompleteUiCustomization:
ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent(intent); Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); ... } } } ); Intent placeAutocompleteIntent = new PlaceAutocomplete.IntentBuilder() .setInitialQuery("INSERT_QUERY_TEXT") .setOrigin(new LatLng(10.0, 10.0)) ... .setAutocompleteUiCustomization( AutocompleteUiCustomization.builder() .listItemIcon(AutocompleteUiIcon.noIcon()) .listDensity(AutocompleteListDensity.MULTI_LINE) .theme(R.style.BrandedTheme) .build()) .build(this); placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);
Ottieni previsioni sui luoghi in modo programmatico
La tua app può ottenere un elenco di nomi e/o indirizzi di luoghi previsti dall'API Autocomplete chiamando PlacesClient.findAutocompletePredictions() e passando un oggetto FindAutocompletePredictionsRequest. L'esempio seguente mostra una chiamata completa a PlacesClient.findAutocompletePredictions().
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Risposte di Autocomplete (New)
L'API restituisce un
FindAutocompletePredictionsResponse
in un
Task.
FindAutocompletePredictionsResponse contiene un elenco di massimo cinque 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 ulteriori informazioni sugli ID luogo in Autocomplete, consulta Place Details (New). Per informazioni generali sugli ID luogo, consulta la panoramica degli ID luogo.getTypes()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.
Parametri obbligatori
Query
La stringa di testo in cui cercare. Specifica parole intere e sottostringhe, nomi di luoghi, indirizzi e plus code. Il servizio Autocomplete (New) restituisce corrispondenze candidate in base a questa stringa e ordina i risultati in base alla loro rilevanza percepita.
Per impostare il parametro di query, chiama il metodo setQuery() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Parametri facoltativi
Tipi principali
Un elenco di massimo cinque valori di tipo della Tabella A o della Tabella B utilizzati per filtrare i luoghi restituiti nella risposta. Un luogo deve corrispondere a uno dei valori del tipo principale specificati per essere incluso nella risposta.
Un luogo può avere un solo tipo principale associato tra i tipi della Tabella A o della Tabella B. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house".
La richiesta viene rifiutata con un errore INVALID_REQUEST se:
- Sono stati specificati più di cinque tipi.
- Vengono specificati tutti i tipi non riconosciuti.
Per impostare il parametro dei tipi principali, chiama il metodo setTypesFilter() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Paesi
Includi solo i risultati dell'elenco dei paesi specificati, indicati come un elenco di massimo 15 valori di due caratteri ccTLD ("dominio di primo livello"). Se omesso, non vengono applicate limitazioni alla risposta. Ad esempio, per limitare le regioni a Germania e Francia:
Se specifichi sia locationRestriction sia includedRegionCodes,
i risultati si trovano nell'area di intersezione delle due impostazioni.
Per impostare il parametro dei paesi, chiama il metodo setCountries() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Offset di input
L'offset dei caratteri Unicode in base zero che indica la posizione del cursore nella query. La posizione del cursore può influire sulle previsioni restituite. Se il campo è vuoto, il valore predefinito è la lunghezza della query.
Per impostare il parametro di offset di input, chiama il metodo setInputOffset() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Bias di località o limitazione della località
Per definire l'area di ricerca, puoi specificare un'influenza della località o una limitazione della località, ma non entrambe. Pensa alla limitazione della località come alla specifica della regione in cui devono trovarsi i risultati e alla preferenza per la località come alla specifica della regione vicino alla quale devono trovarsi i risultati. La differenza principale è che con l'influenza della località, potrebbero comunque essere restituiti risultati al di fuori della regione specificata.
Bias di posizione
Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, non da limitazione, pertanto potrebbero comunque essere restituiti risultati al di fuori dell'area specificata.
Per impostare il parametro di bias di località, chiama il metodo
setLocationBias()durante la creazione dell'oggettoFindAutocompletePredictionsRequest.Limitazione relativa alla località
Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti.
Per impostare il parametro di limitazione della località, chiama il metodo
setLocationRestriction()durante la creazione dell'oggettoFindAutocompletePredictionsRequest.
Specifica la regione di preferenza o limitazione della località come area visibile rettangolare o come cerchio.
Un cerchio è definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0.0. Per la limitazione della località, devi impostare il raggio su un valore maggiore di 0,0. In caso contrario, la richiesta non restituisce risultati.
Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti
lowehighdiagonalmente opposti. Un'area visibile è considerata una regione chiusa, il che significa che include il suo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:- Se
low=high, l'area visibile è costituita da quel singolo punto. - Se
low.longitude>high.longitude, l'intervallo di longitudine viene invertito (l'area visibile attraversa la linea di longitudine di 180 gradi). - Se
low.longitude= -180 gradi ehigh.longitude= 180 gradi, l'area visibile include tutte le longitudini. - Se
low.longitude= 180 gradi ehigh.longitude= -180 gradi, l'intervallo di longitudine è vuoto.
Sia
lowchehighdevono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.- Se
Origine
Il punto di origine da cui calcolare la distanza in linea retta fino alla destinazione (accessibile tramite getDistanceMeters()). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Deve essere specificata come coordinate di latitudine e longitudine:
Per impostare il parametro di origine, chiama il metodo setOrigin() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Codice regione
Il codice regione utilizzato per formattare la risposta, inclusa la formattazione dell'indirizzo, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").
Se specifichi un codice regione non valido, l'API restituisce un errore INVALID_ARGUMENT. Il parametro può influire sui risultati in base alla legge vigente.
Per impostare il parametro del codice regione, chiama il metodo setRegionCode() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Token di sessione
I token di sessione sono stringhe generate dall'utente che monitorano le chiamate di Autocomplete (New), sia quelle effettuate tramite il widget sia quelle programmatiche, come "sessioni". Il completamento automatico utilizza i token di sessione per raggruppare 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; la tua app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatico (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occupa automaticamente).
La funzionalità di completamento automatico 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.
Per impostare il parametro del token di sessione, chiama il metodo setSessionToken() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.
Per saperne di più, consulta Token di sessione.
Esempi di Autocomplete (New)
Utilizza la limitazione della località e l'influenza della località
Il completamento automatico (nuovo) utilizza la priorità IP per impostazione predefinita per controllare l'area di ricerca. Con la personalizzazione in base all'IP, l'API utilizza l'indirizzo IP del dispositivo per personalizzare i risultati. Facoltativamente, puoi utilizzare la limitazione della località o la località di riferimento, ma non entrambe, per specificare un'area di ricerca.
La limitazione della località specifica l'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti. L'esempio seguente utilizza la limitazione della località per limitare la richiesta a una limitazione della località circolare con un raggio di 5000 metri centrato su San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Con l'impostazione di un bias di località, la località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata. L'esempio seguente modifica la richiesta precedente per utilizzare l'impostazione di priorità della località:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Utilizza i tipi principali
Utilizza il parametro primary types per limitare i risultati di una richiesta a un determinato tipo, come elencato nella Tabella A e nella Tabella B. Puoi specificare un array di massimo cinque valori. Se omesso, vengono restituiti tutti i tipi.
L'esempio seguente specifica una stringa di query "Soccer" e utilizza il parametro dei tipi principali per limitare i risultati alle attività di tipo "sporting_goods_store":
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Se ometti il parametro dei tipi principali, i risultati possono includere attività di un tipo che potresti non volere, ad esempio "athletic_field".
Usa origine
Quando includi il parametro origin nella richiesta, specificato come coordinate di latitudine e longitudine, l'API include nella risposta la distanza in linea retta dall'origine alla destinazione (accessibile utilizzando getDistanceMeters()). Questo esempio imposta l'origine sul centro di San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Ottimizzazione del completamento automatico (nuovo)
Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio Autocomplete (New).
Ecco alcune linee guida generali:
- Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico (nuovo) dell'API Maps JavaScript, il widget di completamento automatico (nuovo) di Places SDK for Android o il widget di completamento automatico (nuovo) di Places SDK for iOS.
- Comprendi i campi di dati essenziali di Autocomplete (New) 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 Autocomplete (New), utilizza le maschere di campo nei widget Place Details (New) e Autocomplete (New) per restituire solo i campi di dati di Autocomplete (New) di cui hai bisogno.
Ottimizzazione avanzata dei costi
Valuta l'implementazione programmatica di Autocomplete (New) per accedere allo SKU: Autocomplete Request pricing e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (New). 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 di Place Details (New).
- Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di completamento automatico (nuovo), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.
| Cosa serve per la tua richiesta | Numero medio di richieste di completamento automatico (nuovo) prima che un utente selezioni una previsione | Implementazione consigliata |
|---|---|---|
| Place Details diversi dall'indirizzo e dalla posizione, ad esempio il nome del luogo, lo stato dell'attività o l'orario di apertura | Qualsiasi numero | Autocomplete (New) basato su sessione con Place Details (New) |
| Solo l'indirizzo e la latitudine/longitudine della previsione selezionata | Quattro o meno | Completamento automatico (nuovo) per richiesta con l'API Geocoding |
| Solo l'indirizzo e la latitudine/longitudine della previsione selezionata | Più di quattro | Autocomplete (New) basato su sessione per applicazioni solo per indirizzi |
L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (New) per la tua applicazione, a seconda delle prestazioni di utilizzo di Autocomplete (New). L'efficienza di Autocomplete (New) 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 trovare il numero medio di richieste per la tabella, analizza quanti caratteri un utente digita in media prima di selezionare una previsione di Autocomplete (New) nella tua applicazione.
Autocomplete (New) basato su sessione con Place Details (New)
Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché la tua applicazione richiede Place Details (New), come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Autocomplete (New) deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione, oltre agli SKU 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 Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di dati di Autocomplete (New) di cui hai bisogno.
Implementazione programmatica
Utilizza un
token di sessione
con le tue richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Autocomplete (New)
- Il token di sessione utilizzato nella richiesta Autocomplete (New)
- Il parametro
fieldsche specifica i campi di dati di Autocomplete (New) di cui hai bisogno
Autocomplete (New) per richiesta con l'API Geocoding
Implementa Autocomplete (New) 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 Requests più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è inferiore al costo per sessione di Autocomplete (New).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.
Autocomplete (New) basato su sessione per applicazioni solo per indirizzi
Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Autocomplete (New) supera il costo dei prezzi per sessione, la tua implementazione di Autocomplete (New) deve utilizzare un token di sessione sia per le richieste di Autocomplete (New) sia per la richiesta Place Details (New) associata
per sessione.
1
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget
JavaScript,
Android
o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) 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 richieste Autocomplete (New).
Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Autocomplete (New)
- Il token di sessione utilizzato nella richiesta Autocomplete (New)
- Il parametro
fieldsche specifica i campi, ad esempio indirizzo e geometria
Valuta la possibilità di ritardare le richieste di Autocomplete (New)
Puoi adottare strategie come ritardare una richiesta di Autocomplete (New) 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 Autocomplete (New) per ogni carattere dopo che l'utente ha digitato il terzo carattere, 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 Autocomplete (New) 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 Autocomplete (New) 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 Autocomplete (New):
- Aggiungi limitazioni in base al paese, localizzazione e (per le implementazioni programmatiche) preferenza sulla lingua alla tua implementazione di Autocomplete (New). 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 Autocomplete (New) è 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 Autocomplete (New), 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 (New). 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" restituisce una previsione parziale in Autocomplete (New).
- 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, Autocomplete (New) 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
locationRestriction
. In questo modo, Autocomplete (New) restituisce solo i risultati all'interno di quella regione.