Dettagli luogo (nuovo)

Seleziona la piattaforma: Android iOS JavaScript Web Service

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

Visualizzare i dettagli del luogo

La classe GMSPlace contiene informazioni su un luogo specifico, inclusi tutti i campi di dati mostrati in Campi di dati dei luoghi (novità). Recupera un oggetto GMSPlace chiamando GMSPlacesClient fetchPlaceWithRequest:, passando un oggetto GMSFetchPlaceRequest e un metodo di callback di tipo GMSPlaceResultCallback.

L'oggetto GMSFetchPlaceRequest specifica:

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

Inviare una richiesta di dettagli sul luogo

Questo esempio recupera un luogo tramite ID, passando i seguenti parametri:

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

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

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

SDK Places Swift per iOS (anteprima)

// 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 di Place Details

Places Details restituisce un oggetto GMSPlace contenente i dettagli del luogo. Nell'oggetto GMSPlace vengono compilati solo i campi specificati nell'elenco dei campi.

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) o Date (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 e GMSPlacePropertyBusinessStatus 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 GMSFetchPlaceRequest per specificare i parametri richiesti.

ID luogo

L'ID luogo utilizzato in Places SDK for iOS è lo stesso identificatore utilizzato nell'API Places, in Places SDK for Android e in altre API Google. Ogni ID luogo può fare riferimento a un solo luogo, ma un singolo luogo può avere più di un ID luogo.

Esistono circostanze che possono causare l'assegnazione di un nuovo ID luogo a un luogo. Ad esempio, questo può accadere se un'attività si trasferisce in una nuova sede.

Quando richiedi un luogo specificandone l'ID, puoi stare certo che riceverai sempre lo stesso luogo nella risposta (se il luogo esiste ancora). Tieni presente, tuttavia, che la risposta potrebbe contenere un ID luogo diverso da quello indicato nella richiesta.

Elenco di campi

Quando richiedi i dettagli di un luogo, devi specificare i dati da restituire nell'oggetto GMSPlace per il luogo come maschera di campo. Per definire la maschera di campo, passa un array di valori da GMSPlaceProperty all'oggetto GMSFetchPlaceRequest. La mascheratura dei campi è una buona prassi di progettazione per assicurarti di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti in fatturazione non necessari.

Specifica uno o più dei seguenti campi:

  • I seguenti campi attivano lo SKU Place Details (Only ID) (Dettagli sui luoghi (solo ID)):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

  • I seguenti campi attivano lo SKU Dettagli sui luoghi (solo posizione):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

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

    GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

  • I seguenti campi attivano lo SKU Dettagli dei luoghi (avanzato):

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

  • I seguenti campi attivano lo SKU Dettagli dei luoghi (opzione preferita):

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

SDK Places Swift per iOS (anteprima)

// 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 di 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 notevoli. 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.

sessionToken

I token di sessione sono stringhe generate dagli utenti che monitorano le chiamate di Autocompletamento (Nuovo) come "sessioni". La funzionalità di completamento automatico (nuova) utilizza i token di sessione per agrupare le fasi di query e selezione dei luoghi di una ricerca di completamento automatico dell'utente in una sessione distinta ai fini della fatturazione. I token di sessione vengono passati alle chiamate Place Details (New) che seguono le chiamate Autocomplete (New). Per ulteriori informazioni, consulta Token di sessione.

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 l'eventuale attribuzione o l'attribuzione dell'autore.

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