Completamento automatico (novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

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 un stringa che contiene un input parziale dell'utente, "piz siciliano", con l'area di ricerca solo a Milano, Italia. La risposta contiene quindi un elenco di luoghi previsioni che corrispondono alla stringa di ricerca e all'area di ricerca, come il ristorante chiamata "Sicilian Pizza Kitchen".

Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo desiderato. Puoi creare Dettagli luogo (Novità) per visualizzarne altri informazioni sulle previsioni dei luoghi restituite.

Richieste di completamento automatico (nuove)

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

L'API restituisce un FindAutocompletePredictionsResponse in un Task. La FindAutocompletePredictionsResponse contiene un elenco di massimo cinque AutocompletePrediction oggetti che rappresentano 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 del descrizione che corrisponda alla ricerca con uno stile di tua scelta, utilizzando CharacterStyle Il parametro CharacterStyle è facoltativo. Impostalo su null se non ti serve con qualsiasi evidenziazione.
  • 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 luogo (Nuova). 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 dell'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 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, richiama la funzione setQuery() quando si crea l'oggetto FindAutocompletePredictionsRequest.

Parametri facoltativi

  • Tipi principali

    Un elenco di massimo cinque valori per i tipi Tabella A o Tabella B utilizzato 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, richiama setTypesFilter() quando si crea l'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 ("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 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

    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, richiama la funzione setInputOffset() quando si crea l'oggetto FindAutocompletePredictionsRequest.

  • Bias di località o limitazione 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 bias di località, i risultati al di fuori della regione specificata potrebbero comunque essere restituiti.

    • Bias di località

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

      Per impostare il parametro della parzialità di località, chiama la funzione setLocationBias() quando si crea l'oggetto FindAutocompletePredictionsRequest.

    • Restrizione di località

      Specifica un'area in cui cercare. I risultati al di fuori dell'area specificata non sono restituito.

      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 viene definito dal centro 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'area visibile è considerata un regione chiusa, ovvero include il 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'area visibile vuota genera un errore.

  • Origine

    Il punto di origine da cui calcolare la distanza retta alla destinazione (accesso utilizzando getDistanceMeters()). Se questo valore è omessa, la distanza in linea retta non verrà restituita. Deve essere specificato come coordinate di latitudine e longitudine:

    Per impostare il parametro dell'origine, chiama la funzione setOrigin() quando si crea l'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 degne di nota. 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 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 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. Una volta che una sessione ha concluso, il token non è più valido. la tua app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutti i tipi di pubblicità programmatica sessioni di completamento automatico (quando incorpori un frammento o avvii il completamento automatico utilizzando un intent, l'API se ne occupa 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, vedi Token di sessione.

Esempi di completamento automatico (nuovi)

Utilizzare limitazioni e bias di località

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

La limitazione della località specifica l'area in cui eseguire la ricerca. Risultati al di fuori dell'intervallo specificato non vengono restituite. 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 con un massimo di 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 primari, i risultati possono includere le strutture di un tipo che potrebbe non essere utile, come "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 il completamento automatico (Nuova) anche senza una mappa. Se mostri una mappa, deve essere una mappa di Google. Quando visualizzi previsioni da il servizio Autocomplete (nuovo) senza mappa, deve includere il logo di Google visualizzato in linea con i risultati o i campi di ricerca. Per per ulteriori informazioni, consulta la sezione Visualizzazione del logo Google e attribuzioni.