Ricerca testo (Novità)

Ricerca testuale (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 corrispondenti alla stringa di testo e con eventuali bias di località impostati.

Il servizio è particolarmente utile per creare query ambigue sugli indirizzi in un sistema automatizzato e i componenti diversi dall'indirizzo della stringa potrebbero corrispondere sia agli indirizzi sia ad attività commerciali. Esempi di query ambigue sull'indirizzo 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 restituire zero risultati a meno che non sia impostata una località, ad esempio una regione, una limitazione per località o un bias per località.

Ricerca testuale (Nuova) è simile a Ricerca nelle vicinanze (Novità). La differenza principale tra i due è che Ricerca testuale (Nuova) consente di specificare una stringa di ricerca arbitraria, mentre Ricerca nelle vicinanze (Nuova) richiede un'area specifica in cui eseguire la ricerca.

"10 High Street, UK" o "123 Main Street, US"	Diverse "High Street" nel Regno Unito e diverse "Main Street" negli Stati Uniti. La query non restituisce risultati desiderabili, a meno che non sia impostata una limitazione di località.
"ChainRestaurant New York"	Diverse sedi "ChainRestaurant" a New York; nessun indirizzo né nome della via.
"Via Roma 12, Fiumicino Italia" o "Via Roma 12, Milano"	Solo una "High Street" nella città britannica di Escher; solo una "Main Street" nella città statunitense di Pleasanton CA.
"Nomeristorante unico di New York"	Solo un'attività con questo nome a New York; non è necessario distinguere tra una via e l'altra.
"pizzeria a Roma"	Questa query contiene la sua limitazione di località e "pizzeria" è un tipo di luogo ben definito. Restituisce più risultati.
"[phone]"	Questa query contiene un numero di telefono. Restituisce più risultati per i luoghi associati al numero di telefono in questione. Nota: per ottenere risultati ottimali quando esegui una ricerca su un numero di telefono, includi il codice paese seguito da uno spazio e imposta il parametro region code in modo che corrisponda al codice paese.

Nota: la ricerca testuale (nuova) è disponibile nell'SDK Places per Android 3.3.0 e versioni successive. Per maggiori informazioni, consulta Scegliere la versione dell'SDK.

Richieste di ricerca testuale

Nota: la ricerca di testo fa parte dell'SDK Places per Android (nuovo) e non è disponibile nell'SDK Places per Android.

Una richiesta di Ricerca testuale ha il seguente formato:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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 dei campi in modo che includa solo Place.Field.ID e Place.Field.NAME. Ciò significa che gli oggetti Place nella risposta che rappresentano ogni luogo corrispondente contengono solo quei 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 posizioni dei risultati su 10. Il valore predefinito e il massimo è 20.

  • Limita l'area di ricerca al rettangolo definito dalle coordinate di latitudine e longitudine. Nessuna corrispondenza al di fuori di questa area.

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

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta per qualsiasi classe di richiesta (ad esempio, FetchPlaceRequest). L'annullamento viene effettuato 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 l'addebito della richiesta potrebbe comunque esserti addebitato anche se non viene restituita una risposta.

Risposte Ricerca testuale

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 luogo corrispondente.

• Ogni oggetto Place contiene solo i campi definiti dall'elenco dei campi trasmesso 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.NAME);

Questo elenco di campi indica che ogni oggetto Place nella risposta contiene solo l'ID luogo 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 dati degli oggetti Luogo

Parametri obbligatori

I parametri obbligatori per SearchByTextRequest sono:

• Elenco dei campi

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

  Gli elenchi di campi sono una buona prassi di progettazione per assicurarsi di non richiedere dati superflui, il che contribuisce a evitare tempi di elaborazione e addebiti di fatturazione superflui.

  Specifica uno o più dei seguenti campi:

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

    Place.Field.ID, Place.Field.NAME

  • I seguenti campi attivano lo SKU di Ricerca testuale (Base):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

  • I seguenti campi attivano lo SKU di ricerca testuale (preferito):

    Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

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

• Query di testo

  La stringa di testo in cui cercare, ad esempio: "ristorante", "Via Roma 123" o "luogo migliore da visitare a San Francisco". L'API restituisce le corrispondenze candidati in base a questa stringa e ordina i risultati in base alla 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

  Limita 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 della Tabella B vengono restituiti solo nella risposta. Non puoi utilizzare i valori della Tabella B come filtro.

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

• Differenziazione località

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

  Puoi specificare una limitazione di località o un bias di località, ma non entrambi. Considera la limitazione di località come la specifica della regione in cui devono trovarsi i risultati, mentre il bias di località è la specifica della regione a cui i risultati devono essere vicini, ma che possono essere al di fuori dell'area.

  Nota: se ometti sia il bias per località sia la limitazione relativa alla località, l'API utilizza la differenziazione per IP per impostazione predefinita. Con la differenziazione IP, l'API utilizza l'indirizzo IP del dispositivo per differenziare i risultati.
  Nota: il parametro locationBias può essere sostituito se textQuery contiene una località esplicita, ad esempio Market in Barcelona. In questo caso, locationBias viene ignorato.

  Specifica l'area come un'area visibile rettangolare o come un cerchio.

  • Un cerchio viene definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,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 diagonali opposti al punto più basso e al punto più alto. Il punto più basso segna l'angolo sud-ovest del rettangolo, mentre il punto più alto rappresenta l'angolo nord-est del rettangolo.

    Un'area visibile è considerata una regione chiusa, ovvero include i suoi confini. 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 è composta da quel singolo punto.
    • Se low.longitude > high.longitude, l'intervallo di longitudine viene 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.

    Devono essere compilate entrambe le opzioni, mentre la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

    Ad esempio, per un'area visibile rettangolare, consulta Richieste di ricerca testuale.

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

• Restrizione località

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

  Puoi specificare una limitazione di località o un bias di località, ma non entrambi. Pensa alla limitazione di località come a specificare la regione in cui devono trovarsi i risultati, mentre il bias di località è a specificare la regione in cui i risultati devono essere vicini, ma che possono essere al di fuori dell'area.

  Nota: se ometti sia il bias per località sia la limitazione relativa alla località, l'API utilizza la differenziazione per IP per impostazione predefinita. Con la differenziazione IP, l'API utilizza l'indirizzo IP del dispositivo per differenziare 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 a luoghi da restituire. Il valore deve essere compreso tra 1 e 20 (valore predefinito) inclusi.

  Per impostare il parametro per il numero massimo di 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 allo 0,5 più vicino. Ad esempio, un valore pari a 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, restituisci solo i luoghi aperti all'attività al momento dell'invio della query. Se false, restituisci tutte le attività indipendentemente dallo stato aperto. I luoghi che non specificano l'orario di apertura nel database di Google Places vengono restituiti se imposti questo parametro su false.

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

• Livelli di prezzo

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

  • 1 - Questo luogo offre servizi economici.
  • 2 - Questo luogo offre servizi a prezzi moderati.
  • 3 - Questo luogo offre servizi costosi.
  • 4 - Questo luogo offre servizi molto costosi.
  Nota: il valore intero di 0, che indica che il luogo fornisce 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 ranking dei risultati nella risposta in base al tipo di query:

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

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

• Codice regione

  Il codice regione utilizzato per formattare la risposta, specificato come valore del 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 nel campo dell'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 degne di nota. Ad esempio, il ccTLD 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.

• Livello massimo di filtraggio

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

  Per impostare il parametro di filtro del tipo rigido, chiama il metodo setStrictTypeFiltering() durante la creazione dell'oggetto SearchByTextRequest.