Una ricerca di testo restituisce informazioni su un insieme di luoghi basate su 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 corrispondente alla stringa di testo e a eventuali bias di località impostati.
Il servizio è particolarmente utile per effettuare query su indirizzi ambigui in un sistema automatizzato e i componenti della stringa diversi dall'indirizzo possono corrispondere a attività e indirizzi. Esempi di query sull'indirizzo ambigue 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 regione, limitazione della località o bias di località).
"10 High Street, UK" o "123 Main Street, US" | Più "High Street" nel Regno Unito; più "Main Street" negli Stati Uniti. La query non restituisce risultati auspicabili, a meno che non sia impostata una limitazione di località. |
"Ristorante di catena a New York" | Più sedi di "Ristoranti di catene" a New York; nessun indirizzo o persino 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 in California, Stati Uniti. |
"NomeRistoranteUnico New York" | A New York esiste un solo esercizio con questo nome; non è necessario indicare l'indirizzo. |
"pizzerie a New York" | Questa query contiene la restrizione relativa alla 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 a quel numero di telefono. |
Visualizzare un elenco di luoghi tramite ricerca di testo
Effettua una richiesta di ricerca di testo chiamando
GMSPlacesClient searchByTextWithRequest:
,
passando un
GMSPlaceSearchByTextRequest
oggetto che definisce i parametri di 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 dei campi da restituire nell'oggetto
GMSPlace
, chiamato anche maschera di campo, come definito daGMSPlaceProperty
. Se non specifichi almeno un campo nell'elenco dei campi o se ometti l'elenco dei campi, la chiamata restituisce un errore. - La query di testo.
Questo esempio di richiesta di ricerca di testo specifica che gli oggetti GMSPlace
della risposta contengono il nome e l'ID luogo di ogni oggetto GMSPlace
nei risultati di ricerca. Inoltre, filtra la risposta in modo da restituire solo 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; } } } ];
SDK Places Swift per iOS (anteprima)
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 alla ricerca di testo
L'API di ricerca di testo restituisce un array di corrispondenze sotto forma di oggetti GMSPlace
, con un oggetto GMSPlace
per ogni luogo corrispondente.
Recupera lo stato aperto
L'oggetto GMSPlacesClient
contiene una funzione membro denominata isOpenWithRequest
(isOpenRequest
in Swift e isPlaceOpenRequest
in GooglePlacesSwift) che restituisce una risposta che indica se il luogo è attualmente aperto, in base all'ora specificata nella chiamata.
Questo metodo accetta un singolo argomento di tipo GMSPlaceIsOpenWithRequest
che contiene:
- Un oggetto
GMSPlace
o una stringa che specifica un ID luogo. Per ulteriori informazioni sulla creazione dell'oggetto Place con i campi necessari, consulta Dettagli dei luoghi.
- Un oggetto
NSDate
(Obj-C) oDate
(Swift) facoltativo che specifica l'ora che vuoi controllare. Se non viene specificato alcun orario, il valore predefinito è l'ora corrente. - Un metodo
GMSPlaceOpenStatusResponseCallback
per gestire la risposta. >
Il metodo GMSPlaceIsOpenWithRequest
richiede che i seguenti campi siano impostati nell'oggetto GMSPlace
:
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
Se questi campi non sono forniti nell'oggetto Place o se passi un ID luogo, il metodo utilizza GMSPlacesClient GMSFetchPlaceRequest:
per recuperarli.
isOpenWithRequest
risposta
isOpenWithRequest
restituisce un oggetto GMSPlaceIsOpenResponse
contenente un valore booleano denominato status
che indica se l'attività è aperta, chiusa o se lo stato è sconosciuto.
Lingua | Valore se aperto | Valore se chiuso | Valore se lo stato è sconosciuto |
---|---|---|---|
Swift | .open |
.closed |
.unknown |
Objective-C | GMSPlaceOpenStatusOpen |
GMSPlaceOpenStatusClosed |
GMSPlaceOpenStatusUnknown |
GooglePlacesSwift (anteprima) | true |
false |
nil |
Fatturazione per isOpenWithRequest
- I campi
GMSPlacePropertyUTCOffsetMinutes
eGMSPlacePropertyBusinessStatus
vengono addebitati in base allo SKU dei dati di base. Il resto degli orari di apertura viene addebitato in base allo SKU Dettagli dei luoghi (avanzato). - Se l'oggetto
GMSPlace
ha già questi campi da una richiesta precedente, non ti verrà addebitato alcun importo.
Esempio: effettua una richiesta GMSPlaceIsOpenWithRequest
L'esempio seguente mostra come inizializzare un GMSPlaceIsOpenWithRequest
all'interno di un oggetto GMSPlace
esistente.
Swift
let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil) GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in if let error = error { // Handle Error } switch response.status { case .open: // Handle open case .closed: // Handle closed case .unknown: // Handle unknown } }
Objective-C
GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil]; [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) { if (error) { // Handle error } switch (response.status) { case GMSPlaceOpenStatusOpen: // Handle open case GMSPlaceOpenStatusClosed: // Handle closed case GMSPlaceOpenStatusUnknown: // Handle unknown } }];
GooglePlacesSwift
let isOpenRequest = IsPlaceOpenRequest(place: place) switch await placesClient.isPlaceOpen(with: isOpenRequest) { case .success(let isOpenResponse): switch isOpenResponse.status { case true: // Handle open case false: // Handle closed case nil: // Handle unknown case .failure(let placesError): // Handle error }
Parametri obbligatori
Utilizza l'oggetto GMSPlaceSearchByTextRequest
per specificare i parametri obbligatori per la ricerca.
-
Elenco di campi
Specifica le proprietà dei dati dei luoghi da restituire. Passa 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 pratica di progettazione per assicurarti di non richiedere dati non necessari, il che consente di evitare tempi di elaborazione e costi di fatturazione non necessari.
Specifica uno o più dei seguenti campi:
I seguenti campi attivano lo SKU Ricerca di testo (solo ID):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
I seguenti campi attivano lo SKU Ricerca di testo (di base):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
I seguenti campi attivano lo SKU Ricerca di testo (avanzata):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
I seguenti campi attivano lo SKU di ricerca di testo (opzione preferita):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
-
textQuery
La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante", "123 Via principale" o "miglior posto da visitare a San Francisco".
Parametri facoltativi
Utilizza l'oggetto GMSPlaceSearchByTextRequest
per specificare i parametri facoltativi per la ricerca.
includedType
Limita i risultati ai luoghi 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 pubblico al momento dell'invio della query. Sefalse
, restituisce tutte le attività indipendentemente dallo stato di apertura. I luoghi che non specificano l'orario di apertura nel database di Google Places vengono riportati se imposti questo parametro sufalse
.isStrictTypeFiltering
Utilizzato con il parametro
includeType
. Se impostato sutrue
, vengono restituiti solo i luoghi che corrispondono ai tipi specificati daincludeType
. Se il valore è false, ovvero il valore predefinito, la risposta può contenere luoghi che non corrispondono ai tipi specificati.locationBias
Specifica un'area in cui cercare. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi quelli al di fuori dell'area specificata.
Puoi specificare
locationRestriction
olocationBias
, ma non entrambi. ConsideralocationRestriction
come la regione in cui devono trovarsi i risultati elocationBias
come la regione in cui devono trovarsi i risultati, ma che può essere al di fuori dell'area.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 50000,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 diagonalmente opposti. Il punto più basso segna l'angolo sud-ovest del rettangolo, mentre il punto più alto rappresenta l'angolo nord-est del rettangolo.
Un viewport è 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 è invertito (l'area visibile attraversa la linea di longitudine di 180 gradi). - Se
low.longitude
= -180 gradi ehigh.longitude
= 180 gradi, l'area visibile include tutte le longitudini. - Se
low.longitude
= 180 gradi ehigh.longitude
= -180 gradi, l'intervallo di longitudine è vuoto. - Se
low.latitude
>high.latitude
, l'intervallo di latitudine è vuoto.
- Se
locationRestriction
Specifica un'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti. Specifica la regione come area visibile rettangolare. Consulta la descrizione di
locationBias
per informazioni su come definire l'area visibile.Puoi specificare
locationRestriction
olocationBias
, ma non entrambi. ConsideralocationRestriction
come la regione in cui devono trovarsi i risultati elocationBias
come la regione in cui devono trovarsi i risultati, ma che può 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 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 al valore più vicino a 0,5. Ad esempio, un valore di 0,6 elimina tutti i risultati con una valutazione inferiore a 1,0.
-
priceLevels
Limita la ricerca ai luoghi contrassegnati da 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 il modo in cui i risultati vengono classificati nella risposta in base al tipo di query:
- Per una query categorica come "Ristoranti a New York",
.relevance
(classifica i risultati in base alla pertinenza della ricerca) è l'impostazione predefinita. Puoi impostarerankPreference
su.relevance
o.distance
(classifica i risultati in base alla distanza). - Per una query non categorica come "Mountain View, CA", ti consigliamo di lasciare
rankPreference
non impostato.
- Per una query categorica come "Ristoranti a New York",
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come valore di un 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 del campo 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 significative. Ad esempio, il TLD di primo livello 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.
Mostrare le attribuzioni nell'app
Quando la tua app mostra informazioni ottenute da
GMSPlacesClient
,
come foto e recensioni, deve anche mostrare le attribuzioni richieste.
Ad esempio, la proprietà reviews
dell'oggetto GMSPlacesClient
contiene un array di massimo cinque oggetti GMSPlaceReview
. Ogni oggetto GMSPlaceReview
può contenere attribuzioni e attribuzioni dell'autore.
Se mostri la recensione nella tua app, devi mostrare anche eventuali attribuzioni o attribuzioni dell'autore.
Per saperne di più, consulta la documentazione sulle attribuzioni.