Szczegóły miejsca (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Nowy pakiet SDK Miejsca na iOS udostępnia aplikacji szczegółowe informacje o miejscach, w tym nazwę i adres miejsca, 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) itp. Aby uzyskać dostęp do tych informacji w przypadku konkretnego miejsca, możesz użyć identyfikatora miejsca, czyli stabilnego identyfikatora, który jednoznacznie identyfikuje dane miejsce.

Pobieranie informacji o miejscu

Klasa GMSPlace zawiera informacje o konkretnym miejscu, w tym wszystkie pola danych widoczne w sekcji Pola danych miejsc (nowe). Pobierz obiekt GMSPlace, wywołując funkcję GMSPlacesClient fetchPlaceWithRequest:, przekazując obiekt GMSFetchPlaceRequest i metodę wywołania o typie GMSPlaceResultCallback.

Obiekt GMSFetchPlaceRequest określa:

  • (Wymagane) Identyfikator miejsca, czyli niepowtarzalny identyfikator miejsca w bazie danych Miejsc Google i w Mapach Google.
  • (Wymagane) Lista pól do zwrócenia w obiekcie GMSPlace, zwana też maską pola, zdefiniowana przez parametr GMSPlaceProperty. Jeśli na liście pól nie określisz co najmniej 1 pola lub pominiesz tę listę, wywołanie zwróci błąd.
  • (Opcjonalnie) Kod regionu używany do formatowania odpowiedzi.
  • (Opcjonalnie) Token sesji używany do zakończenia sesji automatycznego uzupełniania (Nowy).

Przesyłanie żądania dotyczącego szczegółów miejsca

W tym przykładzie pobierane jest miejsce według identyfikatora, z parametrami:

  • Identyfikator miejsca ChIJV4k8_9UodTERU5KXbkYpSYs.
  • Lista pól określająca, że należy zwrócić nazwę miejsca i adres URL witryny.
  • GMSPlaceResultCallback, aby przetworzyć wynik.

Interfejs API wywołuje określoną metodę wywołania zwrotnego, przekazując obiekt GMSPlace. Jeśli miejsce nie zostanie znalezione, obiekt miejsca jest pusty.

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

Pakiet SDK Miejsc Swift na iOS (wersja podglądowa)

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

Odpowiedź na pytanie o szczegóły miejsca

Szczegóły miejsca zwracają obiekt GMSPlace zawierający informacje o miejscu. W obiekcie GMSPlace wypełniane są tylko pola określone na liście pól.

Pobieranie stanu otwartości

Obiekt GMSPlacesClient zawiera funkcję członkowską o nazwie isOpenWithRequest (isOpenRequest w Swift i isPlaceOpenRequest w GooglePlacesSwift), która zwraca odpowiedź wskazującą, czy dane miejsce jest obecnie otwarte, na podstawie czasu określonego w wywołaniu.

Ta metoda przyjmuje 1 argument typu GMSPlaceIsOpenWithRequest, który zawiera:

  • Obiekt GMSPlace lub ciąg znaków określający identyfikator miejsca. Więcej informacji o tworzeniu obiektu Miejsce z wymaganymi polami znajdziesz w sekcji Szczegóły miejsca.
  • Opcjonalny obiekt NSDate (Obj-C) lub Date (Swift), który określa czas, jaki chcesz sprawdzić. Jeśli nie podasz czasu, domyślnie zostanie ustawiona bieżąca chwila.
  • Metoda GMSPlaceOpenStatusResponseCallback do obsługi odpowiedzi.
    • >

Metoda GMSPlaceIsOpenWithRequest wymaga ustawienia tych pól w obiekcie GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Jeśli te pola nie są dostępne w obiekcie Miejsce lub jeśli przekazujesz identyfikator miejsca, metoda używa do ich pobierania GMSPlacesClient GMSFetchPlaceRequest:.

isOpenWithRequest odpowiedź

isOpenWithRequest zwraca obiekt GMSPlaceIsOpenResponse zawierający wartość logiczną o nazwie status, która wskazuje, czy firma jest otwarta, zamknięta czy jej stan jest nieznany.

Język Wartość, jeśli jest otwarta Wartość, jeśli jest zamknięta Wartość, jeśli stan jest nieznany
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (wersja testowa) true false nil

Płatności za konto isOpenWithRequest

  • Za pola GMSPlacePropertyUTCOffsetMinutes i GMSPlacePropertyBusinessStatus są naliczane opłaty w ramach SKU danych podstawowych. Pozostałe godziny otwarcia są naliczane zgodnie z kodem SKU Szczegóły miejsca (zaawansowane).
  • Jeśli obiekt GMSPlace już zawiera te pola z poprzedniego zapytania, nie zostanie pobrana kolejna opłata.

Przykład: wysłanie prośby GMSPlaceIsOpenWithRequest

Poniższy przykład pokazuje, jak zainicjować GMSPlaceIsOpenWithRequest w obiekcie GMSPlace.

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
          }

Wymagane parametry

Aby określić wymagane parametry, użyj obiektu GMSFetchPlaceRequest.

Identyfikator miejsca

Identyfikator miejsca używany w pakiecie Places SDK na iOS jest tym samym identyfikatorem, który jest 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 miejsca.

W niektórych okolicznościach miejsce może otrzymać nowy identyfikator. Może się tak zdarzyć, jeśli firma przeniesie się do nowej lokalizacji.

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

Lista pól

Gdy żądasz szczegółów miejsca, musisz określić dane, które mają zostać zwrócone w obiekcie GMSPlace dla tego miejsca jako maska pola. Aby zdefiniować maskę pola, prześlij tablicę wartości z GMSPlaceProperty do obiektu GMSFetchPlaceRequest. Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

Podaj co najmniej 1 z tych pól:

  • Te pola powodują wyświetlenie SKU Szczegóły miejsca docelowego (tylko identyfikator):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

  • Te pola powodują wyświetlenie elementu SKU „Szczegóły miejsca” (tylko lokalizacja):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

  • Te pola powodują wyświetlenie identyfikatora SKU Szczegóły miejsca (podstawowe):

    GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

  • Te pola powodują wyświetlenie identyfikatora SKU Szczegóły miejsca (zaawansowane):

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

  • Te pola powodują wyświetlenie kodu SKU „Szczegóły miejsca” (preferowany):

    GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

W tym przykładzie przekazywana jest lista 2 wartości pól, aby określić, że obiekt GMSPlace zwracany przez żądanie zawiera pola name i 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];

Pakiet SDK Miejsc Swift na iOS (wersja podglądowa)

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

Parametry opcjonalne

Aby określić parametry opcjonalne, użyj obiektu GMSFetchPlaceRequest.

regionCode

Kod regionu użyty do sformatowania odpowiedzi, podany jako 2-znakowy kod CLDR. Ten parametr może też wpływać na wyniki wyszukiwania. Nie ma wartości domyślnej.

Jeśli nazwa kraju w polu adresu w odpowiedzi jest zgodna z kodem regionu, kod kraju jest pomijany w adresie.

Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z niektórymi wyjątkami. Na przykład domeną najwyższego poziomu w Wielkiej Brytanii jest „uk” (.co.uk), a kodem ISO 3166-1 jest „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki w zależności od obowiązujących przepisów.

sessionToken

Tokeny sesji to tworzone przez użytkownika ciągi znaków, które śledzą wywołania funkcji Autouzupełnianie (Nowe) jako „sesje”. Autouzupełnianie (nowa wersja) używa tokenów sesji, aby grupować fazy zapytania i wyboru miejsca w autouzupełnianiu wyszukiwania przez użytkownika w oddzielnej sesji na potrzeby rozliczeń. Tokeny sesji są przekazywane do wywołań Szczegóły miejsca (Nowe), które następują po wywołaniach Autouzupełnianie (Nowe). Więcej informacji znajdziesz w artykule Tokeny sesji.

Wyświetlanie informacji o pochodzeniu danych w aplikacji

Jeśli aplikacja wyświetla informacje uzyskane z GMSPlacesClient, takie jak zdjęcia i opinie, musi też wyświetlać wymagane informacje o źródłach.

Na przykład właściwość reviews obiektu GMSPlacesClient zawiera tablicę zawierającą maksymalnie 5 obiektów GMSPlaceReview. Każdy obiekt GMSPlaceReview może zawierać informacje o źródłach i autorach. Jeśli wyświetlasz opinię w aplikacji, musisz też wyświetlić informacje o źródle lub autora.

Więcej informacji znajdziesz w dokumentacji dotyczącej przypisywania atrybucji.