Completamento automatico (novità)

La funzionalità di completamento automatico (nuova) 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 su parole complete e sottostringhe dell'input, risolvendo i nomi di luoghi, indirizzi e codici plus. La tua applicazione può inviare query mentre l'utente digita per fornire previsioni di query e luoghi in tempo reale.

Ad esempio, chiami il completamento automatico utilizzando come input una stringa contenente un input parziale dell'utente, "pizza siciliana", con l'area di ricerca limitata a San Francisco, in California. La risposta contiene quindi un elenco di predizioni 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 (Nuova) per ottenere ulteriori informazioni su qualsiasi previsione di luogo restituita.

Richieste di completamento automatico (nuove)

La tua app può ottenere un elenco di nomi di luoghi e/o indirizzi previsti dall'API di completamento automatico 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 con 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 nessun luogo conosciuto 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 di testo primario 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 "123 Pitt Street".
• 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 identificativo text che identifica in modo univoco un luogo e che puoi utilizzare per recuperare di nuovo l'oggetto Place in un secondo momento. Per ulteriori informazioni sugli ID luogo in Completamento automatico, consulta Dettagli sul luogo (novità). Per informazioni generali sugli ID luogo, consulta la Panoramica degli 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 in cui cercare. Specifica parole e sottostringhe complete, nomi di luoghi, indirizzi e codici plus. Il servizio Autocompletamento (nuovo) restituisce le 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() quando crei l'oggetto FindAutocompletePredictionsRequest.

Parametri facoltativi

• Tipi principali

  Un elenco di massimo cinque valori di tipo di tipo tra i tipi Tabella A o Tabella B utilizzati per filtrare i luoghi restituiti nella risposta. Un luogo deve corrispondere a uno dei valori di tipo principale specificati per essere incluso nella risposta.

  A un luogo può essere associato un solo tipo principale tra quelli 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.
  • Eventuali tipi non riconosciuti vengono specificati.

  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, specificato come un elenco di massimo 15 valori di due caratteri di ccTLD ("top-level domain"). 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 paesi, chiama il metodo setCountries() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

• Offset di input

  Lo spostamento dei caratteri Unicode a partire da 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 limitazioni di località

  Puoi specificare un bias di località o una limitazione di località, ma non entrambi, per definire l'area di ricerca. Pensa alla restrizione della località come alla specifica della regione in cui devono trovarsi i risultati e alla distorsione della località come alla specifica della regione in cui devono trovarsi i risultati. La differenza principale è che con la predisposizione alla 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 bias, non da limitazione, pertanto i risultati al di fuori dell'area specificata potrebbero comunque essere restituiti.

    Per impostare il parametro di bias di geolocalizzazione, chiama il metodo setLocationBias() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

  • Limitazione di 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 50000,0, inclusi. Il valore predefinito è 0,0. Per la limitazione di 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 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, 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 è 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.

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

• Origine

  Il punto di partenza 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. Deve essere specificato 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 di un ccTLD ("top-level domain"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni notevoli. Ad esempio, il TLD di primo livello del Regno Unito è "uk" (.co.uk), mentre il 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 (nuove) come "sessioni". La funzionalità di completamento automatico utilizza i token di sessione per agrupare le fasi di query e selezione di una ricerca di 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. Al termine di 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'intenzione, l'API si occupa di tutto automaticamente).

  La compilazione automatica 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 token sessione, chiama il metodo setSessionToken() durante la creazione dell'oggetto FindAutocompletePredictionsRequest.

  Per ulteriori informazioni, consulta Token di sessione.

Esempi di completamento automatico (nuovo)

Utilizzare limitazioni e bias di località

Per impostazione predefinita, la funzionalità di completamento automatico (nuova) utilizza la predisposizione IP per controllare l'area di ricerca. Con la predisposizione all'IP, l'API utilizza l'indirizzo IP del dispositivo per orientare i risultati. Se vuoi, puoi utilizzare limitazione della località o bias di località, ma non entrambi, per specificare un'area di ricerca.

La restrizione della località specifica l'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti. L'esempio seguente utilizza la restrizione della località per limitare la richiesta a una restrizione 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 la distorsione della posizione, la posizione funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi quelli al di fuori dell'area specificata. L'esempio seguente modifica la richiesta precedente in modo da utilizzare il bias di geolocalizzazione:

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 essere di un determinato tipo, come indicato 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 "Calcio" 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 l'origine

Quando 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()). In questo esempio l'origine è impostata 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 la funzionalità di completamento automatico (nuova) anche senza una mappa. Se mostri una mappa, deve essere una mappa di Google. Quando mostri le previsioni del servizio Autocompletamento (nuovo) senza una mappa, devi includere il logo di Google visualizzato in linea con il campo di ricerca/i risultati. Per maggiori informazioni, consulta la sezione Visualizzare il logo di Google e le attribuzioni.