Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Questa funzionalità richiede l'abilitazione dell'API Places (Nuova), la nuova generazione dell'API Places. Per maggiori informazioni, consulta Abilitare le API.

Una richiesta di Ricerca nelle vicinanze (Nuova) indica la regione da cercare specificata come un cerchio, definito dalle coordinate di latitudine e longitudine del punto centrale del cerchio e dal raggio in metri. La richiesta restituisce un elenco di luoghi corrispondenti, ciascuno rappresentato da un oggetto 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. Facoltativamente, puoi filtrare la risposta specificando un elenco di tipi di luoghi da includere esplicitamente nella risposta o da escludere. Ad esempio, puoi specificare nella risposta solo i luoghi di tipo "ristorante", "panetteria" e "caffetteria" oppure escludere tutti i luoghi di tipo "scuola".

Richieste Nearby Search (nuove)

Effettua una richiesta di Nearby Search chiamando GMSPlacesClient searchNearbyWithRequest:, passando un oggetto GMSPlaceSearchNearbyRequest che definisca i parametri della richiesta e un metodo di callback, di tipo GMSPlaceSearchNearbyResultCallback, per gestire la risposta.

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

• L'elenco di campi da restituire nell'oggetto GMSPlace, chiamata anche maschera di 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 limitazione di posizione, ovvero il cerchio che definisce l'area di ricerca.

Questo esempio di richiesta di ricerca nelle vicinanze specifica che gli oggetti GMSPlace di risposta contengono il nome del luogo (GMSPlacePropertyName) e le coordinate del luogo (GMSPlacePropertyCoordinate) per ogni oggetto GMSPlace nei risultati di ricerca. Inoltre, filtra la risposta in modo che restituisca solo i luoghi di tipo "ristorante" e "caffetteria".

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

GooglePlacesSwift

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 oggetti GMSPlace, con un oggetto GMSPlace per luogo corrispondente.

Nota: i campi dell'oggetto GMSPlace della risposta non possono essere vuoti. Ad esempio, se l'elenco dei campi include GMSPlacePropertyPhotos per richiedere il campo photos nella risposta e il campo photos nella risposta è vuoto, viene omesso dall'oggetto GMSPlace della risposta.

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

• isOpen calcola se un luogo è aperto a quell'ora.
• isOpenAtDate calcola se un luogo è aperto in una determinata data.

Nota: queste funzioni sono disponibili solo quando abiliti l'SDK Places per iOS. Non sono disponibili quando attivi l'SDK Places per iOS (nuovo). Per maggiori informazioni, consulta Scegliere la versione dell'SDK.

Parametri obbligatori

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

• Elenco dei campi

  Quando richiedi i dettagli sul luogo, devi specificare i dati da restituire nell'oggetto GMSPlace per il luogo come maschera di campo. Per definire la maschera del campo, trasmetti un array di valori da GMSPlaceProperty all'oggetto GMSPlaceSearchNearbyRequest. Il mascheramento dei campi è una buona pratica di progettazione per garantire di non richiedere dati superflui, il che contribuisce a evitare tempi di elaborazione e addebiti di fatturazione superflui.

  Specifica uno o più dei seguenti campi:

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

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

  • I seguenti campi attivano lo SKU di Ricerca nelle vicinanze (avanzata):

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

  • I seguenti campi attivano lo SKU di Ricerca nelle vicinanze (preferito):

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

  L'esempio seguente passa un elenco di due valori di campo per specificare che l'oggetto GMSPlace restituito da una richiesta contiene i 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];
          

  GooglePlacesSwift

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

• locationRestriction

  Un oggetto GMSPlaceLocationRestriction che definisce la regione in cui eseguire la ricerca specificata come un cerchio, definito dal punto centrale e dal raggio 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.

• inclusionTypes/excludedTypes, includedprimaryTypes/excludedprimaryTypes

  Consente di specificare un elenco di tipi dai tipi utilizzati dalla Tabella A per filtrare i risultati di ricerca. È possibile specificare fino a 50 tipi in ogni categoria di limitazione.

  Nota: i valori della Tabella B vengono restituiti solo nella risposta. Non puoi utilizzare i valori della Tabella B come filtro.

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

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

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

  Se ometti includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes dalla richiesta, la ricerca restituisce luoghi per tutti i tipi all'interno dei limiti della limitazione di località.

  includedTypes

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

  excludedTypes

  Un elenco dei tipi di luoghi dalla Tabella A da escludere da una ricerca.

  Se nella richiesta specifichi sia includedTypes (ad esempio "school") sia excludedTypes (ad esempio "primary_school"), la risposta include i luoghi classificati come "school" ma non "primary_school". La risposta include i luoghi che corrispondono ad almeno uno di includedTypes e a nessuno di 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 luoghi principali della Tabella A da includere in una ricerca.

  excludedPrimaryTypes

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

  Se sono presenti tipi principali in conflitto, ad esempio un tipo visualizzato in includedPrimaryTypes e excludedPrimaryTypes, viene restituito un errore INVALID_ARGUMENT.

• maxResultCount

  Specifica il numero massimo di risultati relativi a 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 loro popolarità.
  • .distance I risultati vengono ordinati in ordine crescente in base alla distanza dalla posizione specificata.

• regionCode

  Il codice regione utilizzato per formattare la risposta, specificato come valore del codice CLDR a due caratteri. Non è presente alcun valore predefinito.

  Se il nome del paese nel campo formattedAddress nella risposta corrisponde a regionCode, il codice paese viene omesso da formattedAddress. Questo parametro non ha effetto su adrFormatAddress, che include sempre il nome del paese, o su shortFormattedAddress, che non lo include mai.

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

Attribuzioni display nell'app

Quando l'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 massimo cinque oggetti GMSPlaceReview. Ogni oggetto GMSPlaceReview può contenere attribuzioni e attribuzioni degli autori. Se mostri la recensione nella tua app, devi indicare anche eventuali attribuzioni o attribuzioni dell'autore.

Per ulteriori informazioni, consulta la documentazione sulle attribuzioni.