Ricerca di testo (novità)

Seleziona la piattaforma:Android iOS JavaScript Servizio web

Sviluppatori dello Spazio economico europeo (SEE)

Ricerca testuale (Nuova) restituisce informazioni su un insieme di luoghi in base a una stringa (ad esempio "pizza a New York", "negozi di scarpe vicino a Ottawa" o "123 Main Street"). Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e a qualsiasi bias di località impostato.

Oltre ai parametri obbligatori, Ricerca testuale (nuova) supporta il perfezionamento delle query utilizzando parametri facoltativi per ottenere risultati migliori.

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

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.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 dei campi in modo che includa 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 "Spicy Vegetarian Food".

    • Imposta il numero massimo di luoghi dei risultati su 10. Il valore predefinito e il valore massimo sono 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.

Risposte di Ricerca testuale

La classe SearchByTextResponse rappresenta la risposta di 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 di campi passato nella richiesta.

Ad esempio, se 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 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 Accedi ai campi di dati dell'oggetto Place.

Impaginazione

La classe SearchByTextResponse di Ricerca testuale fornisce l'accesso all'impaginazione dei risultati di ricerca tramite il metodo getPagination(), che restituisce un oggetto Pagination.

Utilizza il metodo hasNextPage() dell'oggetto Pagination per determinare se sono disponibili altre pagine di risultati. Questo metodo restituisce un valore booleano (true o false).

Mentre hasNextPage() restituisce true, chiama il metodo fetchNextPage() per recuperare la pagina di risultati successiva.

L'esempio seguente mostra come verificare se è disponibile una pagina successiva e poi caricarla.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

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 che specificano i campi di dati da restituire. Non esiste un elenco predefinito di campi restituiti nella risposta.

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

    Specifica uno o più dei seguenti campi:

    • I seguenti campi attivano lo SKU Ricerca testuale Essentials ID Only:

      Place.Field.DISPLAY_NAME*
          * Da utilizzare al posto di Place.Field.NAME (ritirato nella versione 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Contiene il nome della risorsa luogo nel formato: places/PLACE_ID.
           Utilizza DISPLAY_NAME per accedere al nome testuale del luogo.

      Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).

    • I seguenti campi attivano lo SKU Ricerca testuale Pro:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Da utilizzare al posto di Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (deprecato).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Da utilizzare al posto di Place.Field.ADDRESS (deprecato).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Da utilizzare al posto di Place.Field.ICON_URL (deprecato).
      Place.Field.LOCATION*
          Da utilizzare al posto di Place.Field.LAT_LNG (deprecato).
      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

      Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).

    • I seguenti campi attivano lo SKU Ricerca testuale Enterprise:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Da utilizzare al posto di Place.Field.PHONE_NUMBER, che è deprecato.
      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*
          * Da utilizzare al posto di Place.Field.USER_RATINGS_TOTAL, che è deprecato.
      Place.Field.WEBSITE_URI

      Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).

    • I seguenti campi attivano lo SKU Ricerca testuale Enterprise Plus:

      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

      Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (novità).

    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 su cui eseguire la ricerca, ad esempio "ristorante", "123 Main Street" o "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

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

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

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

  • Bias di posizione

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

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

    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 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 basso e alto diagonalmente opposti. Il punto più basso indica 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, 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 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.

      Sia il valore di base che il valore finale devono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

      Per un esempio di area visibile rettangolare, consulta Richieste di Ricerca testuale.

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

  • Limitazione relativa alla 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 di Bias di località.

    Puoi specificare la limitazione della località o l'evidenziazione della località, ma non entrambe. Pensa alla limitazione della località come alla specifica della regione in cui devono trovarsi i risultati e all'influenza della località come alla specifica della regione a cui i risultati devono essere vicini, ma possono trovarsi al di fuori dell'area.

    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 di 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 a quelli la cui valutazione media degli utenti è maggiore 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 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 momento dell'invio della query. Se false, restituisci tutte le attività, indipendentemente dallo stato di apertura. 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 i luoghi che forniscono servizi a tutti i livelli di prezzo. Per limitare i risultati in modo da includere solo i 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.

    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", 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 di categoria, ad esempio "Mountain View, CA", ti consigliamo di lasciare il parametro di preferenza di ranking non impostato.

    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 del codice CLDR di due caratteri. Questo parametro può anche avere un effetto di 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 suo 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 del tipo di inclusione. Se impostato su true, vengono restituiti solo i luoghi che corrispondono ai tipi specificati da include type. Se impostato su 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.