Completamento automatico (novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Il completamento automatico (nuova) restituisce previsioni sui 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 complete e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e plus code. L'applicazione può inviare query mentre l'utente digita, per fornire previsioni immediate e sulle query.

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 sui luoghi corrispondenti alla stringa di ricerca e all'area di ricerca, ad esempio il ristorante denominato "Sicilian Pizza Kitchen".

Le previsioni sui luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo desiderato. Puoi inviare una richiesta Dettagli luogo (nuova) per ottenere ulteriori informazioni su qualsiasi previsione del luogo restituita.

Nota: il completamento automatico (novità) è disponibile nell'SDK Places per Android 3.5.0 e versioni successive. Per maggiori informazioni, consulta Scegliere la versione dell'SDK.

Richieste di completamento automatico (nuove)

La tua app può ottenere un elenco di nomi e/o indirizzi dei luoghi previsti dall'API Autocomplete chiamando PlacesClient.findAutocompletePredictions(), trasmettendo 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());
        })
    );

Nota: le chiamate effettuate utilizzando i widget Place Autocomplete chiamano sempre Place Autocomplete, non Place Autocomplete (novità); le chiamate ai widget non sono interessate dal metodo di inizializzazione.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta per una qualsiasi delle classi di richiesta (ad esempio, FetchPlaceRequest). L'annullamento viene eseguito secondo il criterio del "best effort". Una volta inviata una richiesta di annullamento, non verrà restituita alcuna risposta. L'emissione di un token di annullamento NON garantisce che una determinata richiesta verrà annullata e potrebbe esserti comunque addebitato il costo della richiesta anche se non viene restituita una risposta.

Risposte di completamento automatico (nuove)

L'API restituisce FindAutocompletePredictionsResponse in 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 del filtro.

Per ogni luogo previsto, puoi chiamare i seguenti metodi per recuperare i dettagli:

• getFullText(CharacterStyle) restituisce il testo completo della descrizione di un luogo. È 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 utilizzando CharacterStyle. Il parametro CharacterStyle è facoltativo. Impostalo su null se non hai bisogno di evidenziare.
• getPrimaryText(CharacterStyle) restituisce il testo principale che descrive un luogo. che di solito è il nome del luogo. Esempi: "Torre Eiffel" e "Via Cavour 123".
• getSecondaryText(CharacterStyle) restituisce il testo della società controllata della descrizione di un luogo. Questo è utile, ad esempio, come seconda riga quando mostri le previsioni di completamento automatico. Esempi: "Avenue Anatole France, Paris, Francia" e "Sydney, Nuovo Galles del Sud".
• getPlaceId() restituisce l'ID luogo del luogo previsto. Un ID luogo è un identificatore di testo che identifica in modo univoco un luogo, che puoi utilizzare per recuperare l'oggetto Place di nuovo in un secondo momento. Per ulteriori informazioni sugli ID luogo nella funzionalità di completamento automatico, consulta la sezione Dettagli luogo (novità). Per informazioni generali sugli ID luogo, consulta la panoramica degli ID luogo.
• getTypes() restituisce l'elenco dei tipi di luogo associati al luogo.
• getDistanceMeters() restituisce la distanza retta in metri tra questo luogo e l'origine specificata nella richiesta.

Parametri obbligatori

• Query

  La stringa di testo in cui eseguire la ricerca. Specifica parole e sottostringhe complete, nomi di luoghi, indirizzi e plus code. Il servizio di completamento automatico (nuovo) restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla 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 fino a cinque valori di tipo dei tipi Tabella A o Tabella B utilizzati per filtrare le posizioni restituite nella risposta. Un luogo deve corrispondere a uno dei valori di tipo principale specificati da includere nella risposta.

  A un luogo può essere associato un solo tipo principale dei 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 specificati più di cinque tipi.
  • Vengono specificati 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 di paesi specificati, specificati come elenco di massimo 15 valori a 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 countries, chiama il metodo setCountries() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

• Offset di input

  L'offset Unicode su base zero che indica la posizione del cursore nella query. La posizione del cursore può influire sulle previsioni restituite. Se vuoto, viene utilizzata per impostazione predefinita 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 di località

  Puoi specificare una parzialità per località o una limitazione di località, ma non entrambi, per definire l'area di ricerca. La limitazione di località può essere considerata come la specifica della regione in cui devono trovarsi i risultati, mentre la limitazione di località indica la regione alla quale i risultati devono essere vicini. La differenza fondamentale è che, con la bias di località, potrebbero comunque essere restituiti i risultati al di fuori della regione specificata.

  • Bias località

    Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, non da restrizione, quindi i risultati al di fuori dell'area specificata potrebbero comunque essere restituiti.

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

  • Restrizione di località

    Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti.

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

  Specifica la regione della restrizione di località o della restrizione di località come un'area visibile rettangolare o sotto forma di cerchio.

  • Un cerchio viene definito dal centro e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0,0. Per le limitazioni di 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, ovvero include il proprio confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre quelli di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

    Nota: i tipi di bias supportati variano a seconda della versione dell'SDK in uso. CircularBounds è disponibile solo in Completamento automatico (Nuovo).
    • Se low = high, l'area visibile è composta da quel singolo punto.
    • Se low.longitude > high.longitude, l'intervallo di longitudine viene invertito (l'area visibile supera 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.

    È necessario compilare entrambi i campi low e high e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

• Origine

  Il punto di partenza da cui calcolare la distanza in linea retta della destinazione (a cui si accede mediante 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 dell'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 a 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 codice ISO 3166-1 è"gb " (tecnicamente per l'entità "The United Kingdom of Gran Bretagna e Irlanda del Nord").

  Nota: il codice regione deve rappresentare la regione da cui ha origine la richiesta, non necessariamente la regione di destinazione per la query.

  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 completamento automatico (nuove) come "sessioni". Il completamento automatico utilizza i token di sessione per raggruppare le fasi di query e selezione della ricerca di completamento automatico di un 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 terminata una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico programmatico (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occupa automaticamente).

  Il completamento automatico utilizza un elemento AutocompleteSessionToken per identificare ogni sessione. L'app deve passare un nuovo token di sessione all'inizio di ogni nuova sessione e poi trasmettere lo stesso token, insieme a un ID luogo, nella chiamata successiva a fetchPlace() per recuperare i dettagli del luogo per il luogo selezionato dall'utente.

  Per impostare il parametro token di sessione, chiama il metodo setSessionToken() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

  Per maggiori informazioni, consulta Token di sessione.

Esempi di completamento automatico (nuovi)

Usa limitazione di località e bias per località

Il completamento automatico (nuova) utilizza la differenziazione IP per impostazione predefinita per controllare l'area di ricerca. Con la differenziazione per IP, l'API utilizza l'indirizzo IP del dispositivo per differenziazione dei risultati. Facoltativamente, puoi utilizzare limitazione di località o bias di località, ma non entrambi, per specificare un'area in cui eseguire la ricerca.

La limitazione di 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 di località per limitare la richiesta a una limitazione di 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 questa tipologia, la località funge da bias, nel senso che è possibile restituire risultati relativi alla località specificata, compresi quelli al di fuori dell'area specificata. L'esempio successivo modifica la richiesta precedente in modo da utilizzare la differenziazione per 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 tipi principali

Utilizza il parametro tipi principali per limitare i risultati di una richiesta di un determinato tipo come elencato nella Tabella A e nella Tabella B. Puoi specificare un array con un massimo di cinque valori. Se omesso, vengono restituiti tutti i tipi.

L'esempio seguente specifica una stringa di query "Calcio" e utilizza il parametro types primario 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 di tipo primario, i risultati possono includere stabilimenti di tipo che potresti non volere, ad esempio "athletic_field".

Usa origine

Se includi il parametro origin nella richiesta, specificato come coordinate di latitudine e longitudine, l'API include la distanza in linea retta dall'origine alla destinazione nella risposta (a cui si accede 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());
        })
    );

Attribuzioni

Puoi utilizzare il completamento automatico (Nuova) anche senza una mappa. Se mostri una mappa, deve essere una mappa di Google. Quando visualizzi previsioni dal servizio di completamento automatico (nuovo) senza una mappa, devi includere il logo di Google visualizzato in linea con i campi di ricerca o i risultati. Per maggiori informazioni, consulta la sezione Visualizzazione del logo Google e attribuzione.