Ricerca di testo (novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Sviluppatori dello Spazio economico europeo (SEE)

La ricerca testuale (New) 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 che corrispondono alla stringa di testo e a qualsiasi bias di località impostato.

Oltre ai parametri obbligatori, la ricerca testuale (New) supporta l'affinamento delle query utilizzando parametri facoltativi per ottenere risultati migliori.

Ottenere un elenco di luoghi tramite la ricerca testuale

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

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

  • L'elenco dei campi da restituire nell'oggetto GMSPlace, chiamato anche maschera di campo, come definito da GMSPlaceProperty. 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.

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. Filtra anche la risposta in modo da restituire solo i luoghi di tipo "ristorante".

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      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
}

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;
      }
    }
  }
];

Risposte alla ricerca testuale

L'API Ricerca testuale restituisce un array di corrispondenze sotto forma di oggetti GMSPlace, con un oggetto GMSPlace per ogni luogo corrispondente.

Ottenere lo stato di apertura

L'oggetto GMSPlacesClient contiene una funzione membro chiamata 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:

Il metodo GMSPlaceIsOpenWithRequest richiede che i seguenti campi siano impostati nell'oggetto GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Se questi campi non vengono forniti nell'oggetto Place o se passi un ID luogo, il metodo utilizza GMSPlacesClient GMSFetchPlaceRequest: per recuperarli.

Risposta isOpenWithRequest

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
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Fatturazione per isOpenWithRequest

  • I campi GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyBusinessStatus vengono addebitati in base allo SKU Dati di base. Il resto degli orari di apertura viene addebitato in base allo SKU Place Details Enterprise.
  • Se l'oggetto GMSPlace ha già questi campi da una richiesta precedente, non ti verrà addebitato di nuovo.

Esempio: inviare una richiesta GMSPlaceIsOpenWithRequest

L'esempio seguente mostra come inizializzare un GMSPlaceIsOpenWithRequest all'interno di un oggetto GMSPlace esistente.

Places Swift SDK

        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
        }

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
            }
          }];

Impaginazione

La ricerca testuale fornisce un oggetto di impaginazione, il hasNextPage valore booleano, che viene restituito nella prima risposta a una chiamata di ricerca testuale. Se è disponibile una pagina successiva, puoi utilizzare la fetchNextPage() funzione per caricarla.

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

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Parametri obbligatori

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

  • Elenco dei campi

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

    Gli elenchi dei 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 Solo ID di Ricerca testuale Essentials:

      GMSPlacePropertyPlaceID

    • I seguenti campi attivano lo SKU Ricerca testuale Pro:

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

    • I seguenti campi attivano lo SKU Ricerca testuale Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

      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 Main Street" o "il posto migliore 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 che corrispondono al tipo specificato definito da Tabella A. È possibile specificare un solo tipo. Ad esempio:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Se true, restituisce solo i luoghi aperti al pubblico al momento dell'invio della query. Se false, restituisce tutte le attività indipendentemente dallo stato di apertura. I luoghi che non specificano gli orari di apertura nel database di Google Places vengono restituiti se imposti questo parametro su false.

  • isStrictTypeFiltering

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

  • locationBias

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

    Puoi specificare locationRestriction o locationBias, ma non entrambi. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui i risultati devono trovarsi nelle vicinanze, ma possono essere al di fuori dell'area.

    Specifica la regione come area visibile rettangolare o come cerchio.

    • Un cerchio è definito da un punto centrale e da un raggio in metri. Il raggio deve essere compreso tra 0,0 e 50000,0 inclusi. Il raggio predefinito è 0,0. Ad esempio:

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

    • Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due diagonalmente opposti punti basso e alto. 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 e i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

      • Se low = high, l'area visibile è costituita da un 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 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 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 locationBias.

    Puoi specificare locationRestriction o locationBias, ma non entrambi. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui i risultati devono trovarsi nelle vicinanze, ma possono essere al di fuori dell'area.

  • maxResultCount

    Specifica il numero massimo di risultati del luogo 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 è 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 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 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:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    Specifica come vengono classificati i risultati 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) è il valore predefinito. Puoi impostare rankPreference 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.

  • regionCode

    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 del 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 importanti. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è "gb" (tecnicamente per l' entità del "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge applicabile.

  • shouldIncludePureServiceAreaBusinesses

    Se true, restituisce le attività al domicilio del cliente nei risultati di ricerca. Un'attività al domicilio del cliente è un'attività che effettua consegne a domicilio o che raggiunge direttamente i clienti, ma che non presta servizio ai clienti presso l'indirizzo dell'attività.

    Ad esempio:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

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 GMSPlaceReview oggetti. Ogni oggetto GMSPlaceReview può contenere attribuzioni e attribuzioni dell'autore. Se mostri la recensione nella tua app, devi anche mostrare qualsiasi attribuzione o attribuzione dell'autore.

Per saperne di più, consulta la documentazione sulle attribuzioni.