Ricerca testo (Novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

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 "Via Cavour 123". Il servizio risponde con un elenco di luoghi corrispondente alla stringa di testo e a qualsiasi bias di località impostato.

Il servizio è particolarmente utile per creare indirizzi ambigui query in un sistema automatico, e gli altri componenti della stringa potrebbero corrispondere alle attività commerciali e indirizzi IP esterni. Esempi di query di indirizzi ambigui sono gli indirizzi con formattazione scadente o richieste che includono componenti diversi dall'indirizzo, come i nomi delle attività commerciali. Richieste come i primi due esempi potrebbero non restituire risultati, a meno che una località, come regione, limitazione di località o bias località.

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

"Via Roma 10, Italia" o "123 Main Street, US"	Diverse "High Street" nel Regno Unito; più "Main Street" negli Stati Uniti. La query non restituisce risultati desiderabili a meno che non venga applicata una restrizione di località per iniziare.
"ChainRestaurant New York"	Più "ChainRestaurant" sedi a New York; nessun indirizzo oppure e persino il nome della via.
"10 High Street, Escher Regno Unito" 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.
"UniqueRestaurantName New York"	Solo una struttura con questo nome a New York; nessuna via necessari per differenziare.
"pizzerie a Roma"	Questa query contiene la relativa limitazione di località e "pizzerie" sono un tipo di luogo ben definito. Restituisce più risultati.
"[phone]"	Questa query contiene un numero di telefono. Restituisce più risultati per luoghi associati a quel numero di telefono. Nota: per risultati ottimali durante la ricerca su un numero di telefono, includi il prefisso internazionale seguito da uno spazio e imposta region code in modo che corrisponda al codice paese.

Nota: la ricerca testuale (novità) è disponibile nell'SDK Places per Android 3.3.0 e versioni successive. Per ulteriori informazioni, consulta la sezione Scegliere l'SDK dell'audiodescrizione.

Richieste di ricerca testuale

Nota: la ricerca testuale fa parte di SDK Places per Android (nuovo); non è disponibile in 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 corrispondenza contengono solo questi due campi.

• Utilizza SearchByTextRequest.Builder per creare un 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. L'impostazione predefinita e è 20.

  • Limita l'area di ricerca al rettangolo definito da latitudine e e coordinate di longitudine. Non viene restituita nessuna corrispondenza all'esterno di questa area.

• Aggiungi un elemento OnSuccessListener e visualizza i luoghi corrispondenti dal SearchByTextResponse .

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, vedi Inizializza il client API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una delle classi di richiesta (ad esempio, FetchPlaceRequest). L'annullamento avviene 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à annullato e ti potrebbe comunque essere addebitato il costo della richiesta, anche se non viene restituita.

Risposte della Ricerca testuale

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

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

• Ogni oggetto Place contiene solo i campi definiti dall'elenco dei campi passato 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 e il nome di ogni luogo corrispondente. Dopodiché potrai usare 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 Luogo di accesso campi dati oggetto

Parametri obbligatori

I parametri richiesti per SearchByTextRequest sono:

• Elenco campi

  Specifica i campi di dati dei luoghi da restituire. Trasmettere un elenco di Place.Field che specificano i campi di dati da restituire. Non esiste un elenco predefinito di nella risposta.

  Gli elenchi di campi sono una buona prassi di progettazione per garantire di dati non necessari, così da evitare tempi di elaborazione non necessari addebiti di fatturazione.

  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 su cui cercare, ad esempio: "ristorante", "123 Main Street" o "luogo migliore da visitare a San Francisco". L'API restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base sulla loro pertinenza percepita.

  Per impostare il parametro di query di testo, chiama il metodo setTextQuery() durante la creazione dell'oggetto SearchByTextRequest.

Parametri facoltativi

Utilizza la SearchByTextRequest per specificare i parametri facoltativi per la richiesta.

• Tipo incluso

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

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

  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, che significa è possibile restituire risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.

  Puoi specificare la limitazione di località o la differenziazione ma non entrambi. Pensa alla limitazione di località come a specificare regione in cui devono trovarsi i risultati e la differenziazione della località che specifica la regione alla quale i risultati devono essere vicini, ma che possono essere al di fuori della zona.

  Nota: se ometti entrambi bias di località e limitazione di località, l'API utilizza la differenziazione IP per impostazione predefinita. Con la differenziazione per IP, l'API utilizza Indirizzo IP del dispositivo per differenziazione dei risultati.
  Nota: Il parametro locationBias può da sostituire se textQuery contiene una località esplicita, come Market in Barcelona. In questo caso, locationBias viene ignorato.

  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 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 diagonalmente opposte ai punti bassi e alti. Il punto più basso indica il sud-ovest angolo del rettangolo e il punto più alto rappresenta il nord-est angolo del rettangolo.

    Un'area visibile è considerata un regione chiusa, ovvero include il confine. I limiti di latitudine deve essere compreso tra -90 e 90 gradi inclusi e i limiti di longitudine deve essere compreso 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 è invertito (l'area visibile attraversa i 180 gradi longitudine).
    • Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutti 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 vuoto. 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 sono restituito. Specifica la regione come un'area visibile rettangolare. Leggi la descrizione di Bias di località per informazioni sulla definizione dell'area visibile.

  Puoi specificare la limitazione di località o la differenziazione ma non entrambi. Pensa alla limitazione di località come a specificare regione in cui devono trovarsi i risultati e la differenziazione della località che specifica la regione a cui i risultati devono essere vicini, ma che possono essere esterni della zona.

  Nota: se ometti entrambi bias di località e limitazione di località, l'API utilizza la differenziazione IP per impostazione predefinita. Con la differenziazione per IP, l'API utilizza l'indirizzo IP il dispositivo per differenziare i risultati.

  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. Il valore 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 a o uguale a questo limite. I valori devono essere compresi tra 0,0 e 5,0 (incluso) in di 0,5. Ad esempio: 0, 0,5, 1,0, ... , 5,0 inclusi. I valori sono arrotondato per eccesso al valore più vicino a 0,5. Ad esempio, un valore pari a 0,6 elimina tutti 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. nel momento in cui la query viene inviata. Se false, restituisci tutte le attività indipendentemente dallo stato aperto. I luoghi che non specificano l'orario di apertura nel database di Google Places 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 per includere solo luoghi con livelli di prezzo specifici, puoi trasmettere un elenco di valori interi che corrispondono ai livelli di prezzo per i 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 offre servizi senza costi, può essere incluso in una ma non può essere usato 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 categorica come "Ristoranti a New York", SearchByTextRequest.RankPreference.RELEVANCE (ranking dei risultati per pertinenza della ricerca) è l'impostazione predefinita. Puoi impostare la preferenza di ranking su SearchByTextRequest.RankPreference.RELEVANCE oppure SearchByTextRequest.RankPreference.DISTANCE (ranking dei risultati in base alla distanza).
  • Per una query non categorica come "Mountain View, CA", ti consigliamo di lasciare non impostato 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 codice CLDR a due caratteri. Questo parametro può anche avere un effetto bias nei risultati di ricerca. Non esiste un valore predefinito.

  Se il nome del paese nel campo dell'indirizzo nella risposta corrisponde alla il prefisso, il codice del paese viene omesso dall'indirizzo.

  La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk) mentre il codice ISO 3166-1 è "gb" (tecnicamente per persona giuridica del "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 di tipo restrittivo

  Utilizzato con il parametro include type. Se impostato su true, solo le località che corrispondono ai tipi specificati specificati da vengono restituiti il tipo di inclusione. Quando false è il valore predefinito, la risposta può contenere luoghi 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.