Place Details

Places SDK for iOS fornisce alla tua app informazioni dettagliate sui luoghi, tra cui nome e indirizzo del luogo, 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.

Dettagli del luogo

La classe GMSPlace fornisce informazioni su un luogo specifico. Puoi ottenere un oggetto GMSPlace nei seguenti modi:

• Chiama GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Consulta la guida per ottenere il luogo attuale.
• Chiama GMSPlacesClient fetchPlaceFromPlaceID:, passando un GMSPlaceField, un ID luogo e un metodo di callback. Per le richieste Places Details, se non specifichi almeno un campo con una richiesta o se ometti il parametro fields da una richiesta, verranno restituiti TUTTI i campi possibili e ti verrà addebitato l'importo corrispondente. Consulta la guida su come ottenere un luogo tramite ID.

Avviso:se non specifichi almeno un campo con una richiesta o se ometti il parametro fields da una richiesta, VERRANNO restituiti TUTTI i campi possibili e ti verrà addebitato l'importo corrispondente. Questo vale solo per le richieste di dettagli del luogo.

Quando richiedi un luogo, devi specificare i tipi di dati del luogo da restituire. Per farlo, passa un GMSPlaceField, specificando i tipi di dati da restituire. Si tratta di un aspetto importante da considerare, poiché influirà sul costo di ogni richiesta.

Poiché i risultati dei dati sui luoghi non possono essere vuoti, vengono restituiti solo i risultati sui luoghi con dati (ad esempio, se un luogo richiesto non ha foto, il campo photos non sarà presente nel risultato).

L'esempio seguente passa un elenco di due valori di campo per specificare i dati restituiti da una richiesta:

Swift

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

      // Specify the place data types to return.
      let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))
  

Objective-C

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

      // Specify the place data types to return.
      GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
  

GMSPlaceFieldTakeout, GMSPlaceFieldDelivery, GMSPlaceFieldDineIn, GMSPlaceFieldCurbsidePickup, GMSPlaceFieldPhoneNumber, GMSPlaceFieldWebsite, GMSPlaceFieldOpeningHours e GMSPlaceFieldAddressComponents non sono supportati per gli oggetti luogo GMSPlaceLikelihoodList.

Scopri di più sui campi luogo. Per ulteriori informazioni su come vengono fatturate le richieste di dati sui luoghi, consulta Utilizzo e fatturazione.

La classe GMSPlace può contenere i seguenti dati sui luoghi:

• name: il nome del luogo.
• editorialSummary: fornisce una descrizione di un luogo.
• placeID: l'identificatore testuale del luogo. Scopri di più sugli ID luogo nel resto di questa pagina.
• coordinate: la posizione geografica del luogo, specificata come coordinate di latitudine e longitudine.
• phoneNumber: il numero di telefono del luogo, in formato internazionale.
• formattedAddress: l'indirizzo leggibile di questa posizione.

  Spesso questo indirizzo equivale all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni di licenza.

  L'indirizzo formattato è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

  Non analizzare l'indirizzo formattato in modo programmatico. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.

• openingHours: gli orari di apertura del luogo (come rappresentato da GMSOpeningHours). Chiama GMSOpeningHours.weekdayText per ottenere un elenco di stringhe localizzate degli orari di apertura giornalieri per la settimana. Chiama GMSOpeningHours.Periods per restituire un elenco di GMSPeriod con informazioni più dettagliate equivalenti ai dati forniti da weekdayText. Nota:se un luogo è sempre aperto, il periodo di tempo è rappresentato da domenica a mezzanotte e closeEvent è nullo.
• currentOpeningHours e secondaryOpeningHours: campi che tengono conto delle festività e delle modifiche temporanee alla programmazione di un luogo.

• addressComponents: un array di oggetti GMSAddressComponent che rappresentano i componenti dell'indirizzo di un luogo. Questi componenti vengono forniti allo scopo di estrarre informazioni strutturate sull'indirizzo di un luogo, ad esempio trovare la città in cui si trova un luogo. Non utilizzare questi componenti per la formattazione degli indirizzi; utilizza invece la proprietà formattedAddress, che fornisce un indirizzo formattato localizzato.

  Tieni presente quanto segue in merito all'array addressComponents:

  • L'array di componenti dell'indirizzo può contenere più componenti di formattedAddress.
  • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse in formattedAddress.
  • Non è garantito che il formato della risposta rimanga lo stesso tra le richieste. In particolare, il numero di addressComponents varia in base all'indirizzo richiesto e può cambiare nel tempo per lo stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un determinato componente potrebbe mancare in una risposta successiva.
• userRatingsTotal: indica il numero di recensioni che compongono la valutazione del luogo.

La classe GMSPlace contiene le seguenti funzioni membro:

• isOpen calcola se un luogo è aperto in un determinato momento, in base a openingHours e UTCOffsetMinutes, nonché alla data e all'ora attuali.
• isOpenAtDate calcola se un luogo è aperto in una determinata data, in base a openingHours e UTCOffsetMinutes, nonché alla data e all'ora attuali.

Quando utilizzi queste funzioni per ottenere orari e/o date di apertura, la richiesta fetchPlaceFromPlaceID: o findPlaceLikelihoodsFromUserLocationWithPlaceFields: originale deve specificare ENTRAMBI i campi GMSPlaceFieldOpeningHours e GMSPlaceFieldUTCOffsetMinutes. Se uno di questi campi non è presente, l'oggetto GMSPlace risultante non conterrà orari o date di apertura e la chiamata restituirà GMSPlaceOpenStatusUnknown. Per risultati precisi, richiedi i campi GMSPlaceFieldBusinessStatus e GMSPlaceFieldUTCOffsetMinutes nella richiesta del luogo originale. Se non viene richiesta, si presume che l'attività sia operativa.

Per informazioni su come utilizzare isOpen con Place Details, guarda il video Come ottenere gli orari di apertura .

Ottieni ore eccezionali

Mentre gli orari di apertura regolari vengono ottenuti tramite openingHours, currentOpeningHours e secondaryOpeningHours supportano le modifiche temporanee e per le festività. Se disponibili, gli orari eccezionali per questi giorni speciali possono essere filtrati e visualizzati.

Swift

    func examineOpeningHours(place: GMSPlace) {

      // Check if the current opening hours contains a special day that has exceptional hours
      guard let currentOpeningHours = place.currentOpeningHours else { return }
      if let specialDays = currentOpeningHours.specialDays {
        guard !specialDays.isEmpty else { return }
        if let specialDay = specialDays.filter { $0.isExceptional }.first  {
          // Indicate exceptional hours
        }
      }

      // Check if current opening hours contains a truncated time period
      let periods = currentOpeningHours.periods

      if !periods.isEmpty {
        for period in periods {
          let open = period.open
          let close = period.close

          if let open = open {
            let date = open.date

            if open.isTruncated {
              // Indicate truncated time period
            }
          }
        }
      }

      // Check if the place's secondary opening hours indicate when delivery is available
      let secondaryOpeningHours = place.secondaryOpeningHours
      guard let hoursType = secondaryOpeningHours.first?.hoursType else {
      return
      }

      if (hoursType == GMSPlaceHoursTypeDelivery) {
        // Indicate hours where delivery is available
      }
  }

Objective-C

- (void)examineOpeningHours:(GMSPlace *) place {

    // Check if the current opening hours contains a special day that has exceptional hours
    GMSOpeningHours *currentOpeningHours = place.currentOpeningHours;
    if (currentOpeningHours != nil) {
      NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays;
      if ([specialDays count] != 0) {
        for (GMSPlaceSpecialDay *specialDay in specialDays) {
          NSDate *date = specialDay.date;
          if ([specialDay isExceptional]) {
            // Indicate exceptional hours
          }
        }
      }
    }

    // Check if current opening hours contains a truncated time period
    NSArray <GMSPeriod *> * periods = currentOpeningHours.periods;

    if ([periods count] != 0) {
      for (GMSPeriod * period in periods) {
        GMSTimeOfWeek *open = period.open;
        GMSTimeOfWeek *close = period.close;

        if (open) {
          if ([open isTruncated]) {
            // Indicate truncated time period
          }
        }
      }
    }

    // Check if the place's secondary opening hours indicate when delivery is available
    GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours;
    GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType;

    if (hoursType == GMSPlaceHoursTypeDelivery) {
      // Indicate hours where delivery is available
    }
}

Ottieni un luogo in base all'ID

Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Nell'SDK Places per iOS, puoi recuperare l'ID di un luogo da un oggetto GMSPlace. Puoi memorizzare l'ID luogo e utilizzarlo per recuperare l'oggetto GMSPlace in un secondo momento.

Per ottenere un luogo in base all'ID, chiama GMSPlacesClient fetchPlaceFromPlaceID:, passando i seguenti parametri:

• Una stringa contenente un ID luogo.
• Uno o più GMSPlaceField, che specificano i tipi di dati da restituire.
• Un token di sessione se la chiamata viene effettuata per concludere una query di completamento automatico. In caso contrario, passa nil.
• Un 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 luogo è nullo.

Places Swift SDK per iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Swift

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

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

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

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

Visualizzare le attribuzioni nell'app

Quando la tua app mostra informazioni ottenute da GMSPlacesClient lookUpPlaceID:callback:, deve mostrare anche le attribuzioni. Consulta la documentazione sulle attribuzioni.

Scopri di più sugli 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 di 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, ciò può accadere se un'attività si trasferisce in una nuova sede.

Quando richiedi un luogo specificando un ID luogo, puoi essere certo di ricevere 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 della tua richiesta.

Per ulteriori informazioni, consulta la panoramica dell'ID luogo.