Szczegóły miejsc

Pakiet Places SDK na iOS udostępnia aplikacji szczegółowe informacje o miejscach, w tym nazwę i adres miejsca, lokalizację geograficzną określoną jako współrzędne geograficzne, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i inne dane. Aby uzyskać dostęp do tych informacji w przypadku konkretnego miejsca, możesz użyć identyfikatora miejsca, czyli stałego identyfikatora, który jednoznacznie identyfikuje miejsce.

Informacje o miejscu

Klasa GMSPlace zawiera informacje o konkretnym miejscu. Obiekt GMSPlace możesz uzyskać w ten sposób:

• Zadzwoń pod numer GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Zapoznaj się z przewodnikiem po uzyskiwaniu informacji o bieżącym miejscu.
• Wywołaj funkcję GMSPlacesClient fetchPlaceFromPlaceID:, przekazując GMSPlaceField, identyfikator miejsca i metodę wywołania zwrotnego. W przypadku żądań szczegółów miejsca, jeśli nie określisz w żądaniu co najmniej 1 pola lub pominiesz parametr fields, zostaną zwrócone WSZYSTKIE możliwe pola i zostanie naliczona odpowiednia opłata. Zapoznaj się z przewodnikiem po pobieraniu miejsca według identyfikatora.

Gdy wysyłasz prośbę o miejsce, musisz określić, jakie typy danych o miejscu chcesz otrzymać. Aby to zrobić, przekaż znak GMSPlaceField, określając typy danych do zwrócenia. Jest to ważne, ponieważ wpłynie na koszt każdego żądania.

Wyniki danych o miejscach nie mogą być puste, dlatego zwracane są tylko wyniki dotyczące miejsc, które zawierają dane (np. jeśli żądane miejsce nie ma zdjęć, pole photos nie będzie obecne w wyniku).

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

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

      // 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 miejsca. Więcej informacji o tym, jak rozliczane są żądania danych o miejscach, znajdziesz w artykule Wykorzystanie 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 – lokalizacja geograficzna miejsca określona za pomocą współrzędnych geograficznych.
• phoneNumber – numer telefonu miejsca w formacie międzynarodowym.
• formattedAddress – czytelny dla użytkownika adres tej lokalizacji.

  Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, np. Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

  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 programowo. Zamiast tego używaj poszczególnych komponentów adresu, które są uwzględniane w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

• openingHours – godziny otwarcia miejsca (reprezentowane przez GMSOpeningHours). Zadzwoń pod numer GMSOpeningHours.weekdayText, aby uzyskać listę zlokalizowanych ciągów znaków z godzinami otwarcia w poszczególnych dniach tygodnia. Wywołaj GMSOpeningHours.Periods, aby zwrócić listę GMSPeriod z bardziej szczegółowymi informacjami, które są równoważne danym dostarczanym przez weekdayText. Uwaga: jeśli miejsce jest zawsze otwarte, okres jest reprezentowany jako niedziela o północy, a closeEvent ma wartość null.
• currentOpeningHours i secondaryOpeningHours – pola, w których można wprowadzać zmiany w harmonogramie miejsca w święta i w innych okresach.

• 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 się ono znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego użyj właściwości formattedAddress, która zawiera sformatowany adres w odpowiednim języku.

  Pamiętaj o tych informacjach dotyczących 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, z wyjątkiem tych, które są uwzględnione w formattedAddress.
  • Format odpowiedzi nie musi być taki sam w przypadku różnych żądań. W szczególności liczba addressComponents zależy od żądanego adresu i może się zmieniać z czasem 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 – pokazuje, ile opinii składa się na ocenę miejsca.

Klasa GMSPlace zawiera te funkcje składowe:

• isOpen oblicza, czy miejsce jest otwarte o danej godzinie 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.

Jeśli używasz tych funkcji do uzyskiwania godzin lub dat otwarcia, w oryginalnym żądaniu fetchPlaceFromPlaceID: lub findPlaceLikelihoodsFromUserLocationWithPlaceFields: musisz określić OBA pola: GMSPlaceFieldOpeningHours 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 otrzymamy takiej prośby, przyjmujemy, że firma działa.

Informacje o tym, jak używać isOpen ze szczegółami miejsca, znajdziesz w filmie o tym, jak uzyskać godziny otwarcia .

Uzyskiwanie niestandardowych godzin otwarcia

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

- (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 tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. W pakiecie SDK Miejsc na iOS możesz pobrać identyfikator miejsca z obiektu GMSPlace. Możesz zapisać identyfikator miejsca i użyć go później, aby ponownie pobrać obiekt GMSPlace.

Aby uzyskać miejsce według identyfikatora, wywołaj funkcję 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 połączenie 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.

// 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)")
  }
}

// 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)")
  }
})

// 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 autorstwie. Więcej informacji znajdziesz w dokumentacji dotyczącej 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ż 1 identyfikator.

W pewnych okolicznościach miejsce może otrzymać nowy identyfikator. Może się tak zdarzyć na przykład wtedy, gdy firma przeniesie się do nowej lokalizacji.

Gdy wysyłasz prośbę o miejsce, podając jego identyfikator, 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, który różni się od identyfikatora w Twojej prośbie.

Więcej informacji znajdziesz w omówieniu identyfikatorów miejsc.