Completamento automatico (novità)

Completamento automatico (nuovo) restituisce le 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 chiamato "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 (nuova) 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 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 relative ai 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 quando crei l'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, vedi Informazioni sui token di sessione.

Per aggiungere il widget Place Autocomplete alla tua app:

1. (Facoltativo) Definisci un token di sessione. Se non fornisci un token di sessione, il widget ne creerà uno per te.

2. Definisci un autocompleteIntent con i parametri desiderati e il token di sessione.

3. Definisci un ActivityResultLauncher per StartActivityForResult. Questo launcher gestirà il risultato restituito dall'attività di completamento automatico.

4. Gestisci il risultato nel callback di ActivityResultLauncher. Ciò comporta l'estrazione di AutocompletePrediction e AutocompleteSessionToken (se non hai fornito i tuoi), la gestione degli errori e, facoltativamente, l'invio di una richiesta fetchPlace() per ottenere ulteriori dettagli su un luogo.

5. Avvia l'intent utilizzando placeAutocompleteActivityResultLauncher

I seguenti esempi mostrano come aggiungere il widget Place Autocomplete utilizzando sia Kotlin sia 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.
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)

// 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. Gli attributi del tema non 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 di luoghi e/o indirizzi 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 completamento automatico (novità)

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, utilizzando CharacterStyle. Il parametro CharacterStyle è 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'oggetto Place in un secondo momento. Per saperne di più 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 pertinenza 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 dei tipi Tabella A o 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 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 elenco di massimo 15 ccTLD ("dominio di primo livello") valori di due caratteri. 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 countries, chiama il metodo setCountries() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

• Offset di input

  L'offset del carattere Unicode in base zero che indica la posizione del cursore nella query. La posizione del cursore può influire sui suggerimenti restituiti. Se è 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. Considera la limitazione della località come la specifica della regione in cui devono trovarsi i risultati e la distorsione della località come la specifica della regione in cui 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 cercare. 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'oggetto FindAutocompletePredictionsRequest.

  • Limitazione relativa alla località

    Specifica un'area in cui cercare. 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'oggetto FindAutocompletePredictionsRequest.

  Specifica la regione di preferenza della posizione o di limitazione della posizione 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 alcun risultato.

  • Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti low e high diagonalmente 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 e 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 è invertito (l'area visibile attraversa la linea di longitudine di 180 gradi).
    • Se low.longitude = -180 gradi e high.longitude = 180 gradi, il riquadro include tutte le longitudini.
    • Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.

    Sia low che high devono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

• 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 del 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 TLD specifico per paese 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 dagli utenti che monitorano le chiamate di completamento automatico (novità), 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 di completamento automatico dell'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ò 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. Consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatiche (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occupa automaticamente).

  Autocomplete utilizza un AutocompleteSessionToken per identificare ogni sessione. La tua app deve trasmettere un nuovo token di sessione all'inizio di ogni nuova sessione, quindi trasmettere lo stesso token, insieme a un ID luogo, nella chiamata successiva a fetchPlace() per recuperare i Place Details per il 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ù, vedi 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à preferita, 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 centrata 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 la preferenza per l'area:

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 primary types per limitare i risultati agli stabilimenti 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 origine nella richiesta, specificato come coordinate di latitudine e longitudine, l'API include nella risposta la distanza in linea retta dall'origine alla destinazione (a cui si accede utilizzando getDistanceMeters()). Questo esempio imposta l'origine al 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 Autocomplete (New) dell'API Maps JavaScript, il widget Autocomplete (New) di Places SDK for Android o il widget Autocomplete (New) 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 la tua app funzioni 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 dell'utilizzo del servizio Autocompletamento (novità), utilizza le maschere dei campi nei widget Dettagli luogo (novità) e Autocompletamento (novità) per restituire solo i campi dati di Autocompletamento (novità) 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 a Place Details (New).
• Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di Autocomplete (New), 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?

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, bias di località e (per le implementazioni programmatiche) preferenze 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 impostare la località in base alla visualizzazione 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 per nome o indirizzo, utilizza una richiesta Dettagli luogo (nuovo). Se i risultati sono previsti solo in una regione specifica, utilizza la ponderazione della località.
  Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
  • 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 nelle 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. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. 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.