Ricerca di testo (novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

La ricerca di testo (nuova) restituisce informazioni su un insieme di luoghi in base a una stringa, ad esempio "pizza a New York" o "negozi di scarpe vicino a Ottawa" o "123 Main Street". Il servizio risponde con un elenco di luoghi corrispondente alla stringa di testo e a eventuali bias di geolocalizzazione impostati.

Il servizio è particolarmente utile per effettuare query su indirizzi ambigui in un sistema automatizzato e i componenti della stringa diversi dall'indirizzo possono corrispondere a attività e indirizzi. Esempi di query sull'indirizzo ambigue sono indirizzi con formattazione scadente o richieste che includono componenti diversi dall'indirizzo, come i nomi delle attività. Le richieste come i primi due esempi potrebbero non restituire risultati, a meno che non sia impostata una località, come regione, limitazione della località o bias di località.

La ricerca di testo (novità) è simile alla Ricerca nelle vicinanze (novità). La differenza principale tra le due è che la ricerca di testo (nuova) consente di specificare una stringa di ricerca arbitraria, mentre la ricerca nelle vicinanze (nuova) richiede un'area specifica in cui effettuare la ricerca.

"10 High Street, UK" o "123 Main Street, US"	Più "High Street" nel Regno Unito; più "Main Street" negli Stati Uniti. La query non restituisce risultati auspicabili, a meno che non sia impostata una limitazione di località.
"ChainRestaurant New York"	Più sedi di "ChainRestaurant" a New York; nessun indirizzo o persino nome della via.
"10 High Street, Escher UK" o "123 Main Street, Pleasanton US"	Solo una "High Street" nella città di Escher nel Regno Unito; solo una "Main Street" nella città di Pleasanton in California, Stati Uniti.
"UniqueRestaurantName New York"	A New York esiste un solo esercizio con questo nome; non è necessario indicare l'indirizzo.
"pizzerie a New York"	Questa query contiene la restrizione relativa alla località e "pizzerie" è un tipo di luogo ben definito. Restituisce più risultati.
"[phone]"	Questa query contiene un numero di telefono. Restituisce più risultati per i luoghi associati a quel numero di telefono. Nota: per risultati ottimali quando esegui una ricerca su un numero di telefono, includi il codice paese seguito da uno spazio e imposta il parametro regionCode in modo che corrisponda al codice paese. I formati dei numeri di telefono variano in base al paese e l'API tenta di restituire un risultato per questi diversi formati.

Nota: la ricerca di testo (nuova) è disponibile in Places SDK per Android 3.3.0 e versioni successive. Per ulteriori informazioni, vedi Scegliere la versione dell'SDK. Per ulteriori informazioni sull'utilizzo delle API Kotlin aggiunte nella versione 4.0.0, consulta la Panoramica di riferimento.

Richieste di ricerca di testo

Nota: la ricerca di testo fa parte di Places SDK for Android (nuovo) e non è disponibile in Places SDK for Android.

Una richiesta di ricerca di testo ha il seguente formato:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

In questo esempio:

• Imposta l'elenco di campi in modo da includere solo Place.Field.ID e Place.Field.DISPLAY_NAME. Ciò significa che gli oggetti Place nella risposta che rappresentano ogni luogo corrispondente contengono solo questi due campi.

• Utilizza SearchByTextRequest.Builder per creare un oggetto SearchByTextRequest che definisce la ricerca.

  • Imposta la stringa di query di testo su "Cibo vegetariano piccante".

  • Imposta il numero massimo di località dei risultati su 10. Il valore predefinito e il valore massimo è 20.

  • Limita l'area di ricerca al rettangolo definito dalle coordinate di latitudine e longitudine. Non vengono restituite corrispondenze al di fuori di questa area.

• Aggiungi un OnSuccessListener e ottieni i luoghi corrispondenti dall'oggetto SearchByTextResponse.

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, consulta Inizializzare il client dell'API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una 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 ti potrebbe essere addebitato l'importo della richiesta anche se non viene restituita alcuna risposta.

Risposte alla ricerca di testo

La classe SearchByTextResponse rappresenta la risposta a una richiesta di ricerca. Un oggetto SearchByTextResponse contiene:

• Un elenco di oggetti Place che rappresentano tutti i luoghi corrispondenti, con un oggetto Place per ogni luogo corrispondente.

• Ogni oggetto Place contiene solo i campi definiti dall'elenco di campi tramesso nella richiesta.

Ad esempio, nella richiesta hai definito un elenco di campi come:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Questo elenco di campi indica che ogni oggetto Place nella risposta contiene solo l'ID e il nome di ogni luogo corrispondente. Puoi quindi utilizzare i metodi Place.getId() e Place.getName() per accedere a questi campi in ogni oggetto Place.

Per altri esempi di accesso ai dati in un oggetto Place, consulta Accedere ai campi di dati dell'oggetto Luogo.

Parametri obbligatori

I parametri obbligatori per SearchByTextRequest sono:

• Elenco di campi

  Specifica i campi di dati dei luoghi da restituire. Passa un elenco di valori Place.Field che specificano i campi di dati da restituire. Non è presente un elenco predefinito dei campi restituiti nella risposta.

  Gli elenchi di campi sono una buona pratica di progettazione per assicurarti di non richiedere dati non necessari, il che consente di evitare tempi di elaborazione e costi di fatturazione non necessari.

  Specifica uno o più dei seguenti campi:

  • I seguenti campi attivano lo SKU Ricerca di testo (solo ID):

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    Note:

    • Il campo Place.Field.NAME è stato ritirato nella versione 4.0 di Places SDK for Android. Utilizza invece Place.Field.DISPLAY_NAME.
    • Il campo RESOURCE_NAME contiene il nome della risorsa luogo nel formato: places/PLACE_ID. Usa DISPLAY_NAME per accedere al nome del luogo in formato di testo.

  • I seguenti campi attivano lo SKU Ricerca di testo (di base):

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.SHORT_FORMATTED_ADDRESS, Place.Field.SUB_DESTINATIONS, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT
    
    Nota: i campi Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG e Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE sono stati ritirati nella versione 4.0 di Places SDK for Android. Utilizza Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION e Place.ACCESSIBILITY_OPTIONS, rispettivamente. Place.Field.ACCESSIBILITY_OPTIONS è disponibile solo per Place Details (Nuovo).

  • I seguenti campi attivano lo SKU Ricerca di testo (avanzata):

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Nota: i campi Place.Field.PHONE_NUMBER e Place.Field.USER_RATINGS_TOTAL sono stati ritirati nella versione 4.0 di Places SDK for Android. Utilizza Place.Field.INTERNATIONAL_PHONE_NUMBER e Place.USER_RATING_COUNT, rispettivamente.

  • I seguenti campi attivano lo SKU di ricerca di testo (opzione preferita):

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Nota: la versione 4.0 di Places SDK for Android ha introdotto il ritiro di diversi campi di dati dei luoghi e l'aggiunta di nuovi campi. Per ulteriori informazioni, consulta Eseguire la migrazione ai nuovi campi di dati dei luoghi in Places SDK for Android 4.0 .

  Per impostare il parametro dell'elenco di campi, chiama il metodo setPlaceFields() durante la creazione dell'oggetto SearchByTextRequest.

• Query di testo

  La stringa di testo su cui eseguire la ricerca, ad esempio: "ristorante", "123 Main Street" o "il miglior posto da visitare a San Francisco". L'API 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 di testo, chiama il metodo setTextQuery() durante la creazione dell'oggetto SearchByTextRequest.

Parametri facoltativi

Utilizza l'oggetto SearchByTextRequest per specificare i parametri facoltativi per la richiesta.

• Tipo incluso

  Consente di limitare i risultati ai luoghi corrispondenti al tipo specificato definito dalla Tabella A. È possibile specificare un solo tipo. Ad esempio:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Nota: i valori nella Tabella B vengono restituiti solo nella risposta. Non puoi utilizzare i valori della Tabella B come filtro.

  Per impostare il parametro di tipo incluso, chiama il metodo setIncludedType() durante la creazione dell'oggetto SearchByTextRequest.

• Bias di località

  Specifica un'area in cui cercare. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi quelli al di fuori dell'area specificata.

  Puoi specificare la limitazione della località o la preferenza per una località, ma non entrambe. Considera la limitazione della località come la specifica della regione in cui devono trovarsi i risultati e la preferenza per la località come la specifica della regione in cui i risultati si troveranno probabilmente o nelle vicinanze, tenendo presente che, quando utilizzi la preferenza per la località, i risultati possono comunque trovarsi al di fuori dell'area specificata.

  Nota: se ometti sia la bias di geolocalizzazione sia la limitazione della posizione, l'API utilizza per impostazione predefinita il bias di IP. Con la distorsione IP, l'API utilizza l'indirizzo IP del dispositivo per distorcere i risultati.
  Nota: il parametro locationBias può essere override se textQuery contiene una posizione esplicita come Market in Barcelona. In questo caso, locationBias viene ignorato.

  Specifica la regione 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. Ad esempio:

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

  • Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti bassi e alti diagonalmente opposti. Il punto più basso segna l'angolo sud-ovest del rettangolo, mentre il punto più alto rappresenta l'angolo nord-est del rettangolo.

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

    Sia il valore minimo che quello massimo devono essere inseriti e la casella rappresentata non può essere vuota. Un viewport vuoto genera un errore.

    Ad esempio, per un viewport rettangolare, consulta Richieste di ricerca di testo.

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

• Limitazione di località

  Specifica un'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti. Specifica la regione come area visibile rettangolare. Per informazioni sulla definizione dell'area visibile, consulta la descrizione del bias di località.

  Puoi specificare la limitazione della località o la preferenza per una località, ma non entrambe. Pensa alla limitazione 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, ma che può essere al di fuori dell'area.

  Nota: se ometti sia la bias di geolocalizzazione sia la limitazione della posizione, l'API utilizza per impostazione predefinita il bias di IP. Con la predisposizione IP, l'API utilizza l'indirizzo IP del dispositivo per influenzare i risultati.

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

• Numero massimo di risultati

  Specifica il numero massimo di risultati relativi ai luoghi da restituire. Deve essere compreso tra 1 e 20 (valore predefinito) inclusi.

  Per impostare il parametro del conteggio massimo dei risultati, chiama il metodo setMaxResultCount() durante la creazione dell'oggetto SearchByTextRequest.

• Valutazione minima

  Limita i risultati solo a quelli la cui valutazione media degli utenti è superiore o uguale a questo limite. I valori devono essere compresi tra 0,0 e 5,0 (inclusi) con incrementi di 0,5. Ad esempio: 0, 0,5, 1,0, ..., 5,0 inclusi. I valori vengono arrotondati per eccesso al valore più vicino a 0,5. Ad esempio, un valore di 0,6 elimina tutti i risultati con una valutazione inferiore a 1,0.

  Per impostare il parametro di valutazione minima, chiama il metodo setMinRating() durante la creazione dell'oggetto SearchByTextRequest.

• Aperto adesso

  Se true, restituisce solo i luoghi aperti al pubblico al momento dell'invio della query. Se false, restituisce tutte le attività indipendentemente dallo stato di apertura. I luoghi che non specificano l'orario di apertura nel database di Google Places vengono riportati se imposti questo parametro su false.

  Per impostare il parametro Aperto ora, chiama il metodo setOpenNow() durante la creazione dell'oggetto SearchByTextRequest.

• Livelli di prezzo

  Per impostazione predefinita, i risultati includono i luoghi che offrono servizi a tutti i livelli di prezzo. Per limitare i risultati in modo da includere solo luoghi con determinati livelli di prezzo, puoi passare un elenco di valori interi corrispondenti ai livelli di prezzo dei luoghi che vuoi restituire:

  • 1 - Il luogo offre servizi economici.
  • 2 - Il luogo offre servizi a prezzi moderati.
  • 3 - Il luogo offre servizi costosi.
  • 4 - Il luogo offre servizi molto costosi.
  Nota: il valore intero 0, che indica che il luogo offre servizi senza costi, può essere incluso in una risposta, ma non può essere utilizzato come valore di filtro in una richiesta.

  Per impostare il parametro dei livelli di prezzo, chiama il metodo setPriceLevels() durante la creazione dell'oggetto SearchByTextRequest.

• Preferenza di ranking

  Specifica il modo in cui i risultati vengono classificati nella risposta in base al tipo di query:

  • Per una query categorica come "Ristoranti a New York", SearchByTextRequest.RankPreference.RELEVANCE (classifica i risultati in base alla pertinenza della ricerca) è l'impostazione predefinita. Puoi impostare la preferenza di ranking su SearchByTextRequest.RankPreference.RELEVANCE o SearchByTextRequest.RankPreference.DISTANCE (classifica i risultati in base alla distanza).
  • Per una query non categorica come "Mountain View, CA", consigliamo di lasciare il parametro di preferenza del ranking non impostato.

  Per impostare il parametro di preferenza del ranking, chiama il metodo setRankPreference() durante la creazione dell'oggetto SearchByTextRequest.

• Codice regione

  Il codice regione utilizzato per formattare la risposta, specificato come valore di un codice CLDR a due caratteri. Questo parametro può anche avere un effetto di bias sui risultati di ricerca. Non è presente alcun valore predefinito.

  Se il nome del paese del campo indirizzo nella risposta corrisponde al codice regione, il codice paese viene omesso dall'indirizzo.

  La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni significative. 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"). 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 SearchByTextRequest.

• Filtro dei tipi rigoroso

  Utilizzato con il parametro di tipo di inclusione. Se impostato su true, vengono restituiti solo i luoghi corrispondenti ai tipi specificati da include type. Se il valore è false, il valore predefinito, la risposta può contenere luoghi che non corrispondono ai tipi specificati.

  Per impostare il parametro di filtro dei tipi rigoroso, chiama il metodo setStrictTypeFiltering() durante la creazione dell'oggetto SearchByTextRequest.