Ricerca testo (Novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Una ricerca testuale restituisce informazioni su un insieme di luoghi in base a una stringa. Ad esempio, "pizza a Roma", "negozi di scarpe vicino a Ottawa" o "Via Roma 123". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e qualsiasi bias per località impostato.

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, ad esempio i nomi delle attività. Richieste come i primi due esempi potrebbero restituire zero risultati, a meno che non venga impostata una località (ad es. regione, limitazione di località o bias di località).

"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à.
"Catena di ristoranti New York" Più sedi di "catene di ristoranti" 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.

Visualizza un elenco di luoghi tramite la ricerca testuale

Effettua una richiesta di ricerca testuale chiamando GMSPlacesClient searchByTextWithRequest:, passando un oggetto GMSPlaceSearchByTextRequest che definisce i parametri della richiesta e un metodo di callback, di tipo GMSPlaceSearchByTextResultCallback, per gestire la risposta.

L'oggetto GMSPlaceSearchByTextRequest specifica tutti i parametri obbligatori e facoltativi per la richiesta. I parametri obbligatori includono:

  • L'elenco di campi da restituire nell'oggetto GMSPlace, chiamato anche maschera del campo, come definito da GMSPlaceProperty. Se non specifichi almeno un campo nell'elenco dei campi oppure se ometti l'elenco dei campi, la chiamata restituisce un errore.
  • La query di testo.

Questa richiesta di ricerca testuale di esempio specifica che gli oggetti GMSPlace di risposta contengono il nome e l'ID del luogo per ogni oggetto GMSPlace nei risultati di ricerca. Inoltre, filtra la risposta per restituire solo i luoghi di tipo "ristorante".

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

GooglePlacesSwift

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Risposte della Ricerca testuale

L'API Text Search restituisce un array di corrispondenze sotto forma di oggetti GMSPlace, con un oggetto GMSPlace per posizione corrispondente.

Oltre ai campi di dati, l'oggetto GMSPlace della risposta contiene le seguenti funzioni membro:

  • isOpen calcola se un luogo è aperto in un determinato momento.
  • isOpenAtDate calcola se un luogo è aperto in una determinata data.

Parametri obbligatori

Utilizza l'oggetto GMSPlaceSearchByTextRequest per specificare i parametri richiesti per la ricerca.

  • Elenco campi

    Specifica le proprietà dei dati dei luoghi da restituire. Trasmetti un elenco di proprietà GMSPlace che specificano i campi di dati da restituire. Se ometti la maschera del campo, la richiesta restituirà un errore.

    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):

      GMSPlacePropertyPlaceID, GMSPlacePropertyName

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

      GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyFormattedAddress, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyCoordinate, GMSPlacePropertyPhotos, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance

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

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

      GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

  • textQuery

    La stringa di testo su cui cercare, ad esempio: "ristorante", "via principale 123" o "luogo migliore da visitare a San Francisco".

Parametri facoltativi

Utilizza l'oggetto GMSPlaceSearchByTextRequest per specificare i parametri facoltativi per la ricerca.

  • includedType

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

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

    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.

  • isStrictTypeFiltering

    Utilizzato con il parametro includeType. Se impostato su true, vengono restituite solo le posizioni che corrispondono ai tipi specificati da includeType. Se il valore è false, il valore predefinito è la risposta che può contenere posizioni che non corrispondono ai tipi specificati.

  • locationBias

    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 locationRestriction o locationBias, ma non entrambi. Pensa a locationRestriction come a specificare la regione in cui devono trovarsi i risultati, e a locationBias a a specificare la regione vicina ai risultati, che però 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. Il raggio predefinito è 0,0. Ad esempio:

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • 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.

  • locationRestriction

    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 locationBias per informazioni sulla definizione dell'area visibile.

    Puoi specificare locationRestriction o locationBias, ma non entrambi. Pensa a locationRestriction come a specificare la regione in cui devono trovarsi i risultati, e a locationBias a a specificare la regione vicina ai risultati, che però possono essere al di fuori dell'area.

  • maxResultCount

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

  • minRating

    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.

  • priceLevels

    Restringi la ricerca ai luoghi contrassegnati a determinati livelli di prezzo. Per impostazione predefinita, vengono selezionati tutti i livelli di prezzo.

    Specifica un array di uno o più valori definiti da PriceLevel.

    Ad esempio:

    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    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 è .relevance (classifica i risultati in base alla pertinenza della ricerca). Puoi impostare rankPreference su .relevance o .distance (ranking dei risultati in base alla distanza).
    • Per una query non categorica come "Mountain View, CA", ti consigliamo di lasciare rankPreference non impostato.

  • regionCode

    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.

Attribuzioni display nell'app

Quando la tua app mostra informazioni ottenute da GMSPlacesClient, come foto e recensioni, deve mostrare anche le attribuzioni richieste.

Ad esempio, la proprietà reviews dell'oggetto GMSPlacesClient contiene un array di un massimo di cinque GMSPlaceReview oggetti. Ogni oggetto GMSPlaceReview può contenere attribuzioni e attribuzioni dell'autore. Se mostri la recensione nell'app, devi mostrare anche eventuali attribuzioni o attribuzioni dell'autore.

Per ulteriori informazioni, consulta la documentazione sulle attribuzioni.