Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Una richiesta di Nearby Search (nuova) prende come input la regione da cercare specificato come un cerchio, definito dalle coordinate di latitudine e longitudine del punto centrale del cerchio e il raggio in metri. La richiesta restituisce un elenco di luoghi corrispondenti, ognuno dei quali è rappresentato da un GMSPlace all'interno dell'area di ricerca specificata.

Per impostazione predefinita, la risposta contiene luoghi di tutti i tipi all'interno dell'area di ricerca. In via facoltativa, filtra la risposta specificando un elenco di tipi di luoghi da includere o escludere in modo esplicito dalla risposta. Ad esempio, puoi specificare di includere nella risposta solo le parti del tipo "ristorante", "panetteria" e "caffetteria" o escludi tutti i luoghi di tipo "scuola".

Richieste di Ricerca nelle vicinanze (nuova)

Fai una richiesta di ricerca nelle vicinanze chiamando GMSPlacesClient searchNearbyWithRequest:, passando un GMSPlaceSearchNearbyRequest che definisce i parametri della richiesta e un metodo di callback, di tipo GMSPlaceSearchNearbyResultCallback, per gestire la risposta.

L'oggetto GMSPlaceSearchNearbyRequest specifica tutti gli obbligatorio e facoltativo parametri per la richiesta. I parametri obbligatori includono:

  • L'elenco di campi da restituire nell'oggetto GMSPlace, chiamato anche maschera del campo, come definita GMSPlaceProperty. Se non specifichi almeno un campo nell'elenco dei campi o se ometti all'elenco dei campi, la chiamata restituisce un errore.
  • La limitazione di località, ovvero il cerchio che definisce l'area di ricerca.

Questo esempio di richiesta di ricerca nelle vicinanze specifica che la risposta GMSPlace oggetti contenere il nome del luogo (GMSPlacePropertyName) e le relative coordinate (GMSPlacePropertyCoordinate) per ogni oggetto GMSPlace nella ricerca che consentono di analizzare i dati e visualizzare i risultati. Inoltre, filtra la risposta per restituire solo i luoghi di tipo "ristorante" e "caffè".

Swift

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

Objective-C

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

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

SDK Places Swift per iOS (anteprima)

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Risposte di Ricerca nelle vicinanze

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

Ottieni stato di apertura

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'orario specificato nella chiamata.

Questo metodo prende un singolo argomento di tipo GMSPlaceIsOpenWithRequest che contiene:

  • Un oggetto GMSPlace o una stringa che specifica un ID luogo. Per ulteriori informazioni sulla creazione di un oggetto Place con i campi necessari, consulta Dettagli luogo.
  • Un oggetto facoltativo NSDate (Obj-C) o Date (Swift) che specifica l'ora da controllare. Se non viene specificata alcuna ora, il valore predefinito è ora.
  • Un metodo GMSPlaceOpenStatusResponseCallback per gestire la risposta.
    • >
di Gemini Advanced.

Il metodo GMSPlaceIsOpenWithRequest richiede l'impostazione dei seguenti campi 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.

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 stato sconosciuto
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (anteprima) true false nil

Fatturazione per isOpenWithRequest

  • I campi GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyBusinessStatus vengono addebitati in base allo SKU di base dei dati. Il resto dell'orario di apertura viene addebitato mediante lo SKU Place Details (Advanced).
  • Se l'oggetto GMSPlace presenta già questi campi di una richiesta precedente, non ti verrà addebitato alcun costo.

Esempio: invia una richiesta GMSPlaceIsOpenWithRequest

L'esempio seguente mostra come inizializzare 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 GMSPlaceSearchNearbyRequest per specificare i parametri richiesti per la ricerca.

  • Elenco campi

    Quando richiedi i dettagli del luogo, devi specificare i dati da ritorna nell'oggetto GMSPlace per il luogo come maschera di campo. Per definire maschera di campo, passa un array di valori GMSPlaceProperty all'oggetto GMSPlaceSearchNearbyRequest. Il mascheramento dei campi è una buona prassi di progettazione per evitare di richiedere dati non necessari, evitando così inutili tempi di elaborazione e addebiti.

    Specifica uno o più dei seguenti campi:

    • I seguenti campi attivano la funzione SKU Ricerca nelle vicinanze (base):

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

    • I seguenti campi attivano la funzione SKU Ricerca nelle vicinanze (avanzata):

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

    • I seguenti campi attivano la funzione SKU Ricerca nelle vicinanze (preferito):

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

    L'esempio seguente trasmette un elenco di due valori del campo per specificare che l'oggetto GMSPlace restituito da una richiesta contiene Campi name e placeID:

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    Objective-C

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

    SDK Places Swift per iOS (anteprima)

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

  • locationRestriction

    Un GMSPlaceLocationRestriction che definisce la regione da ricercare specificata come un cerchio, definita dal punto centrale in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il raggio predefinito è 0,0. Devi impostarlo nella richiesta su un valore maggiore di 0,0.

Parametri facoltativi

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

  • InclusoType/excludedTypes, IncludeMainTypes/excludedprimaryTypes

    Consente di specificare un elenco di tipi da Tabella A utilizzata per filtrare nei risultati di ricerca. È possibile specificare fino a 50 tipi per ogni categoria di limitazione dei tipi.

    Un luogo può avere un solo singolo tipo principale tra i tipi Tabella A associata a li annotino. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house". Utilizza le funzionalità di includedPrimaryTypes e excludedPrimaryTypes per filtrare i risultati in base a il tipo principale di un luogo.

    Un luogo può anche avere più valori di tipo di tipi Tabella A associate. Ad esempio, un ristorante potrebbe avere i seguenti tipi: "seafood_restaurant", "restaurant", "food" "point_of_interest" "establishment". Usa includedTypes e excludedTypes per filtrare i risultati nell'elenco dei tipi associati a un luogo.

    Se specifichi un tipo principale generale, ad esempio "restaurant" o "hotel", la risposta può contenere luoghi con un tipo principale più specifico rispetto a quello specificato. Ad esempio, specifichi di includere un tipo primario di "restaurant". La risposta può quindi contenere luoghi con un tipo principale "restaurant", ma la risposta può anche contenere luoghi con un indirizzo di tipo principale, come "chinese_restaurant" o "seafood_restaurant".

    Se una ricerca viene specificata con più limitazioni di tipo, solo luoghi che soddisfano tutte le restrizioni. Ad esempio, se specifichi {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, i luoghi restituiti offrono servizi correlati a "restaurant", ma non operano principalmente come "steak_house".

    includedTypes

    Un elenco dei tipi di luogo da Tabella A da cercare. Se questo parametro viene omesso, vengono restituiti luoghi di tutti i tipi.

    excludedTypes

    Un elenco di tipi di luogo da Tabella A da escludere da una eseguire una ricerca.

    Se specifichi sia includedTypes (ad esempio "school") sia excludedTypes (ad es. "primary_school") nella richiesta, quindi la la risposta include luoghi classificati come "school" ma non come "primary_school". La risposta include i luoghi che corrispondono ad almeno uno di includedTypes e nessuno dei excludedTypes.

    Se sono presenti tipi in conflitto, ad esempio un tipo visualizzato in includedTypes e excludedTypes, viene restituito un errore INVALID_REQUEST.

    includedPrimaryTypes

    Un elenco dei tipi di luogo principali da Tabella A da includere in una ricerca.

    excludedPrimaryTypes

    Un elenco dei tipi di luogo principali da Tabella A da escludere da una ricerca.

    Se sono presenti tipi principali in conflitto, ad esempio un tipo che compare in includedPrimaryTypes e excludedPrimaryTypes, Viene restituito l'errore INVALID_ARGUMENT.

  • maxResultCount

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

  • rankPreference

    Il tipo di ranking da utilizzare. Se questo parametro viene omesso, i risultati vengono classificati in base alla popolarità. Può essere uno dei seguenti:

    • .popularity (predefinito) Ordina i risultati in base alla popolarità.
    • .distance Ordina i risultati in ordine crescente in base alla loro distanza dal località specificata.

  • regionCode

    Il codice regione utilizzato per formattare la risposta, specificato come codice CLDR a due caratteri. Non esiste un valore predefinito.

    Se il nome del paese nel campo formattedAddress nella risposta corrisponde al regionCode, il codice paese è omesso da formattedAddress. Questo parametro non ha effetto sul valore adrFormatAddress, che include sempre il paese oppure su shortFormattedAddress, che non lo include mai.

    La maggior parte dei codici CLDR è identica a i 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.

Attribuzioni display nell'app

Quando la tua app mostra informazioni ottenute da GMSPlacesClient, come foto e recensioni, nell'app devono essere mostrate anche le attribuzioni richieste.

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

Per ulteriori informazioni, consulta la documentazione su attribuzioni.