Completamento automatico (novità)

Completamento automatico (nuovo) restituisce le previsioni relative ai luoghi in risposta a una richiesta che include una stringa di ricerca di testo 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 al volo.

Ad esempio, chiami il completamento automatico utilizzando come input una stringa che contiene un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, CA. 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 inviare una richiesta Places Details (New) per ottenere ulteriori informazioni su una qualsiasi delle previsioni di 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 durante la digitazione dell'utente.
• Recupera in modo programmatico le previsioni sui luoghi: chiama l'API direttamente per recuperare le previsioni e visualizzarle in un'interfaccia utente personalizzata.

Aggiungere il widget Place Autocomplete

Per fornire 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 sui 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 sui luoghi.

Come quando ottieni le previsioni dei luoghi in modo programmatico, il widget Place Autocomplete ti consente di utilizzare i token di sessione per raggruppare le richieste di completamento automatico in sessioni 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 potrai 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 avvio 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 che 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);

Ottenere previsioni dei 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(), 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 (nuovo)

L'API restituisce un FindAutocompletePredictionsResponse in un Task. FindAutocompletePredictionsResponse contiene un elenco di un massimo di 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. Di solito si tratta del nome del luogo. Esempi: "Torre Eiffel" e "Via Roma, 123".
• getSecondaryText(CharacterStyle) restituisce il testo secondario di una descrizione del 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, che puoi utilizzare per recuperare l'oggetto Place in un secondo momento. Per ulteriori informazioni sugli ID luogo in Autocomplete, consulta Places Details (New). Per informazioni generali sugli ID luogo, consulta la panoramica dell'ID luogo.
• getTypes() restituisce l'elenco dei tipi di luoghi 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 su cui eseguire la ricerca. 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 ricerca, chiama il metodo setQuery() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

Parametri facoltativi

• Tipi principali

  Un elenco di massimo cinque valori di tipo da 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.

  A un luogo può essere associato un solo tipo principale tra i tipi Tabella A o 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 elenco di massimo 15 valori ccTLD ("dominio di primo livello") 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 che 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 del carattere Unicode in base zero che indica la posizione del cursore nella query. La posizione del cursore può influire sulle previsioni restituite. 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à

  Puoi specificare una preferenza di località o una limitazione della località, ma non entrambe, per definire l'area di ricerca. Considera la restrizione sulla 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 la distorsione della località, i risultati al di fuori della regione specificata potrebbero comunque essere restituiti.

  • Bias di località

    Specifica un'area in cui cercare. Questa località funge da preferenza, non da limitazione, quindi i risultati al di fuori dell'area specificata potrebbero comunque essere restituiti.

    Per impostare il parametro di distorsione della località, chiama il metodo setLocationBias() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

  • Limitazione della 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 bias di località o di 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 alcun risultato.

  • Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti low e high diagonalmente opposti. Un viewport è considerato 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 tra -180 e 180 gradi inclusi:

    • Se low = high, l'area visibile è costituita da un unico 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, l'area visibile include tutte le longitudini.
    • Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.

    low e high devono essere entrambi compilati e la casella rappresentata non può essere vuota. Un viewport vuoto genera un errore.

• Origine

  Il punto di origine da cui calcolare la distanza in linea retta fino alla destinazione (a cui si accede utilizzando getDistanceMeters()). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Devono essere specificate 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 ("top-level domain"). La maggior parte dei codici ccTLD sono identici 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 (nuovo), sia quelle effettuate tramite il widget sia quelle programmatiche, come "sessioni". Autocomplete 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 terminata una sessione, il token non è più valido; la tua 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).

  La funzionalità di completamento automatico utilizza un AutocompleteSessionToken per identificare ogni sessione. La tua 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 maggiori informazioni, consulta la sezione Token di sessione.

Esempi di completamento automatico (nuovo)

Utilizzare la limitazione della località e la preferenza per la località

Il completamento automatico (nuovo) utilizza per impostazione predefinita la ponderazione IP per controllare l'area di ricerca. Con la distorsione IP, l'API utilizza l'indirizzo IP del dispositivo per distorcere i risultati. Puoi utilizzare facoltativamente la limitazione della località o la distorsione della località, ma non entrambe, per specificare un'area di ricerca.

La limitazione della posizione 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 posizione per limitare la richiesta a una limitazione della posizione 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 la distorsione della posizione, la posizione funge da distorsione, il che significa che possono essere restituiti risultati intorno alla posizione specificata, inclusi risultati al di fuori dell'area specificata. L'esempio successivo modifica la richiesta precedente per utilizzare la preferenza di 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());
        })
    );

Utilizzare 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.

Il seguente esempio 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".

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