Szczegóły miejsc

Pakiet Places SDK for iOS dostarcza aplikacji szczegółowe informacje o miejscach, w tym ich nazwy i adresy, położenie geograficzne określone jako współrzędne szerokości i długości geograficznej, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i inne. Aby uzyskać dostęp do tych informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca, czyli stałego identyfikatora, który jednoznacznie identyfikuje miejsce.

Informacje o miejscu

Klasa GMSPlace dostarcza informacji o konkretnym miejscu. Obiekt GMSPlace możesz uzyskać na te sposoby:

Gdy wysyłasz żądanie dotyczące miejsca, musisz określić, jakie typy danych o miejscu mają zostać zwrócone. Aby to zrobić, przekaż GMSPlaceField, określając typy danych do zwrócenia. Jest to ważna kwestia, ponieważ wpływa na koszt każdego żądania.

Ponieważ wyniki danych o miejscu nie mogą być puste, zwracane są tylko wyniki z danymi (np. jeśli żądane miejsce nie ma zdjęć, pole photos nie będzie widoczne w wyniku).

W przykładzie poniżej przekazujemy listę 2 wartości pól, aby określić dane zwracane przez żądanie:

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

Dowiedz się więcej o polach miejsc. Więcej informacji o tym, jak rozliczane są żądania danych o miejscach, znajdziesz w artykule Użycie i rozliczenia.

Klasa GMSPlace może zawierać te dane o miejscu:

  • name – nazwa miejsca.
  • editorialSummary – zawiera opis miejsca.
  • placeID – tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
  • coordinate – położenie geograficzne miejsca określone jako współrzędne szerokości i długości geograficznej.
  • phoneNumber – numer telefonu miejsca w formacie międzynarodowym.
  • formattedAddress – zrozumiały dla człowieka adres tej lokalizacji.

    Często jest on taki sam jak adres pocztowy. Pamiętaj, że w niektórych krajach, np. w Wielkiej Brytanii, ze względu na ograniczenia licencyjne nie można rozpowszechniać prawdziwych adresów pocztowych.

    Sformatowany adres składa się logicznie z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer domu), „8th Avenue” (ulica), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które odpowiedź interfejsu API zawiera oprócz sformatowanego pola adresu.

  • openingHours – godziny otwarcia miejsca (reprezentowane przez GMSOpeningHours). Wywołaj GMSOpeningHours.weekdayText, aby uzyskać listę zlokalizowanych ciągów tekstowych z godzinami otwarcia w poszczególnych dniach tygodnia. Wywołaj GMSOpeningHours.Periods, aby zwrócić listę GMSPeriod z bardziej szczegółowymi informacjami, które odpowiadają danym dostarczonym przez weekdayText. Uwaga: jeśli miejsce jest zawsze otwarte, przedział czasu jest reprezentowany jako niedziela o północy, a wartość closeEvent jest równa null.
  • currentOpeningHours i secondaryOpeningHours – pola, które uwzględniają zmiany świąteczne i tymczasowe w harmonogramie miejsca.

  • addressComponents – tablica obiektów GMSAddressComponent reprezentujących komponenty adresu miejsca. Te komponenty służą do wyodrębniania uporządkowanych informacji o adresie miejsca, np. do znajdowania miasta, w którym znajduje się dane miejsce. Nie używaj tych komponentów do formatowania adresu. Zamiast tego użyj właściwości formattedAddress, która udostępnia sformatowany adres w języku lokalnym.

    Zwróć uwagę na te fakty dotyczące tablicy addressComponents:

    • Tablica komponentów adresu może zawierać więcej komponentów niż formattedAddress.
    • Tablica nie musi zawierać wszystkich jednostek politycznych, które zawierają adres, oprócz tych, które są zawarte w formattedAddress.
    • Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności liczba addressComponents różni się w zależności od żądanego adresu i może się zmieniać w czasie w przypadku tego samego adresu. Komponent może zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.
  • userRatingsTotal – liczba opinii, na podstawie których obliczono ocenę miejsca.

Klasa GMSPlace zawiera te funkcje składowe:

  • isOpen oblicza, czy miejsce jest otwarte w danym momencie, na podstawie openingHours i UTCOffsetMinutes oraz bieżącej daty i godziny.
  • isOpenAtDate oblicza, czy miejsce jest otwarte w danym dniu, na podstawie openingHours i UTCOffsetMinutes, oraz bieżącej daty i godziny.

    • Gdy używasz tych funkcji do uzyskiwania godzin lub dat otwarcia, pierwotne żądanie fetchPlaceFromPlaceID: lub findPlaceLikelihoodsFromUserLocationWithPlaceFields: musi określać ZARÓWNO pole GMSPlaceFieldOpeningHours, jak i GMSPlaceFieldUTCOffsetMinutes. Jeśli brakuje któregoś z tych pól, wynikowy obiekt GMSPlace nie będzie zawierać godzin ani dat otwarcia, a wywołanie zwróci GMSPlaceOpenStatusUnknown. Aby uzyskać dokładne wyniki, w pierwotnym żądaniu dotyczącym miejsca poproś o pola GMSPlaceFieldBusinessStatus i GMSPlaceFieldUTCOffsetMinutes. Jeśli nie zostanie przesłana prośba, przyjmiemy, że firma działa.

    Aby dowiedzieć się, jak używać parametru isOpen z informacjami o miejscu, obejrzyj film o tym, jak uzyskać godziny otwarcia .

Uzyskaj niestandardowe godziny otwarcia

Zwykłe godziny otwarcia są pobierane z openingHours, ale currentOpeningHours i secondaryOpeningHours obsługują zmiany harmonogramu w święta i tymczasowe zmiany harmonogramu. Jeśli są dostępne, można filtrować i wyświetlać niestandardowe godziny otwarcia w te dni.

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

Pobieranie miejsca według identyfikatora

Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. W pakiecie Places SDK for iOS możesz pobrać identyfikator miejsca z obiektu GMSPlace. Możesz zapisać identyfikator miejsca i użyć go później do ponownego pobrania obiektu GMSPlace.

Aby uzyskać miejsce według identyfikatora, wywołaj GMSPlacesClient fetchPlaceFromPlaceID:, przekazując te parametry:

  • Ciąg tekstowy zawierający identyfikator miejsca.
  • Co najmniej 1 GMSPlaceField określający typy danych do zwrócenia.
  • Token sesji, jeśli wywołanie jest wykonywane w celu zakończenia zapytania autouzupełniania. W przeciwnym razie przekaż wartość nil.
  • GMSPlaceResultCallback do obsługi wyniku.

Interfejs API wywołuje określoną metodę wywołania zwrotnego, przekazując obiekt GMSPlace. Jeśli miejsce nie zostanie znalezione, obiekt miejsca będzie miał wartość nil.

Pakiet SDK Miejsc w języku Swift na 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]);
  }
}];

Wyświetlanie atrybucji w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z GMSPlacesClient lookUpPlaceID:callback:, musi też wyświetlać informacje o źródle. Zapoznaj się z dokumentacją dotyczącą atrybucji.

Więcej informacji o identyfikatorach miejsc

Identyfikator miejsca używany w pakiecie Places SDK na iOS jest taki sam jak identyfikator używany w interfejsie Places API, pakiecie Places SDK na Androida i innych interfejsach API Google.

Każdy identyfikator miejsca może odnosić się tylko do jednego miejsca, ale jedno miejsce może mieć więcej niż jeden identyfikator.

W niektórych okolicznościach miejsce może otrzymać nowy identyfikator miejsca. Może się tak zdarzyć na przykład wtedy, gdy firma zmieni lokalizację.

Gdy wysyłasz żądanie dotyczące miejsca, podając jego identyfikator miejsca, możesz mieć pewność, że w odpowiedzi zawsze otrzymasz to samo miejsce (jeśli nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż ten w żądaniu.

Więcej informacji znajdziesz w omówieniu identyfikatora miejsca.