Dettagli luogo (nuovo)

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.

L'SDK Places for iOS (nuovo) fornisce alla tua app informazioni dettagliate sui luoghi, tra cui nome e indirizzo, posizione geografica specificata come coordinate di latitudine/longitudine, tipo di luogo (ad esempio discoteca, negozio di animali, museo) e altro ancora. Per accedere a queste informazioni per un luogo specifico, puoi utilizzare l'ID luogo, un identificatore stabile che identifica in modo univoco un luogo.

Visualizza i dettagli del luogo

La classe GMSPlace contiene informazioni su un luogo specifico, inclusi tutti i campi di dati mostrati in Campi dei dati del luogo (nuovo). Per ottenere un oggetto GMSPlace chiama GMSPlacesClient fetchPlaceWithRequest:, passa un oggetto GMSFetchPlaceRequest e un metodo di callback di tipo GMSPlaceResultCallback.

L'oggetto GMSFetchPlaceRequest specifica:

• (Obbligatorio) L'ID luogo, un identificatore univoco di un luogo nel database di Google Places e su Google Maps.
• (Obbligatorio) L'elenco dei 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.
• (Facoltativo) Il codice regione utilizzato per formattare la risposta.
• (Facoltativo) Il token di sessione utilizzato per terminare una sessione di completamento automatico (nuova).

Invia una richiesta Dettagli luogo

Questo esempio restituisce un luogo in base all'ID, passando i seguenti parametri:

• L'ID luogo di ChIJV4k8_9UodTERU5KXbkYpSYs.
• Un elenco di campi che specifica di restituire il nome del luogo e l'URL del sito web.
• Un elemento GMSPlaceResultCallback per gestire il risultato.

L'API richiama il metodo di callback specificato, passando un oggetto GMSPlace. Se il luogo non viene trovato, l'oggetto Place è nullo.

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

GooglePlacesSwift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Risposta Place Details

Place Details restituisce un oggetto GMSPlace contenente i dettagli del luogo. Solo i campi specificati nell'elenco dei campi vengono compilati nell'oggetto GMSPlace.

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 GMSFetchPlaceRequest per specificare i parametri richiesti.

ID luogo

L'ID luogo utilizzato nell'SDK Places per iOS è lo stesso identificatore utilizzato nell'API Places, nell'SDK Places per Android e in altre API di Google. Ogni ID luogo può fare riferimento a una sola località, ma una singola posizione può avere più di un ID luogo.

In alcuni casi, un luogo potrebbe ottenere un nuovo ID luogo. Ad esempio, questo può accadere se un'attività si trasferisce in una nuova sede.

Quando richiedi un luogo specificando un ID luogo, hai la certezza che riceverai sempre lo stesso luogo nella risposta (se il luogo esiste ancora). Tuttavia, tieni presente che la risposta potrebbe contenere un ID luogo diverso da quello della richiesta.

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, trasferisci un array di valori da GMSPlaceProperty all'oggetto GMSFetchPlaceRequest. Il mascheramento dei campi è una buona pratica di progettazione per garantire di non richiedere dati non necessari, 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 Place Details (solo ID):

  GMSPlacePropertyPlaceID, GMSPlacePropertyName e GMSPlacePropertyPhotos

• I seguenti campi attivano lo SKU Place Details (Location Only):

  GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

• I seguenti campi attivano lo SKU Place Details (di base):

  GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes e GMSPlacePropertyWheelchairAccessibleEntrance

• I seguenti campi attivano lo SKU Place Details (Advanced):

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

• I seguenti campi attivano lo SKU di Place Details (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]
    

Parametri facoltativi

Utilizza l'oggetto GMSFetchPlaceRequest per specificare i parametri facoltativi.

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 di bias sui risultati di ricerca. Non è presente alcun 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à di "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge vigente.

sessionToken

I token di sessione sono stringhe generate dall'utente che tracciano le chiamate di completamento automatico (nuovo) come "sessioni". Il completamento automatico (nuova) utilizza i token di sessione per raggruppare la query e inserire le fasi di selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. I token di sessione vengono passati in chiamate Place Details (New) che seguono le chiamate di completamento automatico (Nuova). Per ulteriori informazioni, consulta la sezione Token sessione.

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.