Ricerca testo (Novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

La 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 gli eventuali bias di località impostati.

Il servizio è particolarmente utile per eseguire query di indirizzi ambigue in un sistema automatico; i componenti diversi dall'indirizzo della stringa potrebbero corrispondere ad attività e indirizzi. Esempi di query di indirizzi ambigui sono gli indirizzi con formattazione scadente o le richieste che includono componenti diversi dall'indirizzo, come i nomi delle attività. Richieste come i primi due esempi potrebbero restituire zero risultati, a meno che non venga impostata una località, ad esempio regione, limitazione di località o bias di località.

Ricerca testuale (nuova) è simile a Ricerca nelle vicinanze (nuova). La principale differenza 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 effettuare la ricerca.

"10 High Street, UK" o "123 Main Street, US" Diverse "High Street" nel Regno Unito; diverse "Main Street" negli Stati Uniti. La query non restituisce risultati desiderabili a meno che non venga impostata una limitazione di località.
"ChainRestaurant New York" Più punti vendita "ChainRestaurant" a New York; nessun indirizzo o 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, CA, negli Stati Uniti.
"UniqueRestaurantName New York" Solo una struttura con questo nome a New York; non è necessario distinguere la via.
"pizzerie a Roma" Questa query contiene la relativa limitazione di località e "pizzerie" è un tipo di luogo ben definito. Restituisce più risultati.
"+1 514-670-8700"

Questa query contiene un numero di telefono. Restituisce più risultati per i luoghi associati al numero di telefono.

Richieste di ricerca testuale

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 questi due campi.

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

    • Imposta la stringa della 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. Non viene restituita nessuna corrispondenza all'esterno di questa area.

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

Risposte della Ricerca testuale

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

  • Un elenco di Place oggetti 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 passati nella richiesta.

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

// 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 dei dati dell'oggetto Luogo di accesso.

Parametri obbligatori

I parametri obbligatori per SearchByTextRequest sono:

  • Elenco campi

    Specifica i campi di dati dei luoghi da restituire. Trasmetti un elenco di valori di Place.Field che specificano i campi di dati da restituire. La risposta non contiene un elenco predefinito dei campi restituiti.

    Gli elenchi di campi sono una buona prassi di progettazione per evitare di richiedere dati superflui, evitando così tempi di elaborazione e addebiti non necessari.

    Specifica uno o più dei seguenti campi:

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

      Place.Field.ID, Place.Field.NAME

    • I seguenti campi attivano lo SKU Ricerca testuale (di 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 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 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 da cercare, ad esempio "ristorante", "123 Main Street" o "il posto migliore da visitare a San Francisco". L'API 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 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 tua richiesta.

  • Tipo incluso

    Limita i risultati alle posizioni corrispondenti al tipo specificato definito dalla Tabella A. È possibile specificare un solo tipo. Ad esempio:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

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

  • Bias località

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

    Puoi specificare limitazioni di località o bias per località, ma non entrambi. 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, ma che possono essere al di fuori dell'area.

    Specifica la regione come area visibile rettangolare o circolare.

    • Un cerchio viene definito dal centro 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 bassi e alti opposti diagonalmente. Il punto basso segna l'angolo sud-ovest del rettangolo, mentre il punto alto rappresenta l'angolo nord-est del rettangolo.

      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:

      • 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.
      • Se low.latitude > high.latitude, l'intervallo di latitudine è vuoto.

      Devono essere compilati sia il valore basso che quello alto e 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 Bias di località, chiama il metodo setLocationBias() durante la creazione dell'oggetto SearchByTextRequest.

  • Restrizione di località

    Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti. Specifica la regione come un'area visibile rettangolare. Consulta la descrizione di Bias di posizione per informazioni su come definire l'area visibile.

    Puoi specificare limitazioni di località o bias per località, ma non entrambi. 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, ma che possono essere al di fuori dell'area.

    Per impostare il parametro della limitazione di 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 numero massimo di risultati, chiama il metodo setMaxResultCount() durante la creazione dell'oggetto SearchByTextRequest.

  • Valutazione minima

    Limita i risultati solo agli utenti con valutazione media degli utenti superiore o uguale a questo limite. I valori devono essere compresi tra 0,0 e 5,0 (incluso) con incrementi di 0,5. Ad esempio: 0, 0,5, 1,0, ... , 5,0 inclusi. I valori vengono arrotondati per eccesso al valore più prossimo allo 0,5. 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, restituisce solo i luoghi aperti al momento dell'invio della query. Se false, restituisci tutte le attività indipendentemente dallo stato aperto. Se imposti questo parametro su false, vengono restituiti i luoghi che non specificano l'orario di apertura nel database di Google Places.

    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 che includano solo luoghi a determinati livelli di prezzo, puoi passare un elenco di valori interi che corrispondono ai livelli di prezzo per i luoghi da 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.

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

  • Preferenza di ranking

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

    • Per una query con categoria come "Ristoranti a New York", il valore predefinito è 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 (ranking dei risultati in base alla distanza).
    • Per una query non categorica come "Mountain View, CA", ti consigliamo di non impostare il parametro di preferenza di ranking.

    Per impostare il parametro di 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 di codice CLDR a due caratteri. Questo parametro può anche avere un effetto bias sui risultati di ricerca. Non esiste un 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à "The United Kingdom of 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 di tipo restrittivo

    Utilizzato con il parametro include type. Se impostato su true, vengono restituite solo le posizioni che corrispondono ai tipi specificati per il tipo di inclusione. Quando false è il valore predefinito, la risposta può contenere posizioni che non corrispondono ai tipi specificati.

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