Place Details (最新)

選取平台： Android iOS JavaScript 網頁服務

iOS 版 Places SDK (新版) 可為應用程式提供豐富的地點資訊，包括地點名稱和地址、以經緯度座標指定的地理位置、地點類型 (例如夜店、寵物店、博物館) 等等。如要存取特定地點的這類資訊，您可以使用地點 ID，這是用於識別地點的固定 ID。

取得 Place Details

GMSPlace 類別包含特定地點的相關資訊，包括地點資料欄位 (新版) 中顯示的所有資料欄位。呼叫 GMSPlacesClient fetchPlaceWithRequest:，傳遞 GMSFetchPlaceRequest 物件和 GMSPlaceResultCallback 類型的回呼方法，即可取得 GMSPlace 物件。

GMSFetchPlaceRequest 物件會指定：

  • (必要) 地點 ID：Google 地點介面集資料庫和 Google 地圖中某個地點的專屬 ID。
  • (必填) 在 GMSPlace 物件中傳回的欄位清單，也稱為 GMSPlaceProperty 定義的欄位遮罩。如果您未在欄位清單中指定至少一個欄位，或是省略欄位清單，則呼叫會傳回錯誤。
  • (選用) 用於格式化回應的區域代碼。
  • (選用) 用於結束 Autocomplete (New) 工作階段的工作階段符記。

提出 Place Details 要求

本範例會傳遞下列參數，藉此取得 ID 為 ID 的地點：

  • ChIJV4k8_9UodTERU5KXbkYpSYs 的地點 ID。
  • 指定要傳回地點名稱和網站網址的欄位清單。
  • 用於處理結果的 GMSPlaceResultCallback。

API 會呼叫指定的回呼方法，並傳入 GMSPlace 物件。如果找不到地點，則地點物件為空值。

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

iOS 版 Places Swift SDK (預先發布版)

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

Place Details 回應

Place Details 會傳回 GMSPlace 物件，其中包含地點的詳細資料。GMSPlace 物件中只會填入欄位清單中指定的欄位。

取得開放狀態

GMSPlacesClient 物件包含名為 isOpenWithRequest 的會員函式 (在 Swift 中為 isOpenRequest，在 GooglePlacesSwift 中為 isPlaceOpenRequest)，可根據呼叫中指定的時間，傳回回應，指出地點目前是否營業。

這個方法會使用單一 GMSPlaceIsOpenWithRequest 類型的引數，其中包含：

  • GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何建立含有必要欄位的 Place 物件，請參閱「地點詳細資料」。
  • 選用的 NSDate (Obj-C) 或 Date (Swift) 物件，可指定您要檢查的時間。如未指定時間，則預設為現在。
  • 用於處理回應的 GMSPlaceOpenStatusResponseCallback 方法。
    • >

GMSPlaceIsOpenWithRequest 方法需要在 GMSPlace 物件中設定下列欄位：

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

如果 Place 物件未提供這些欄位，或是您傳遞地點 ID，該方法會使用 GMSPlacesClient GMSFetchPlaceRequest: 擷取這些欄位。

isOpenWithRequest 則回應

isOpenWithRequest 會傳回 GMSPlaceIsOpenResponse 物件，其中包含名為 status 的布林值，可指出商家是否營業、是否已關閉，或狀態不明。

語言 值 (如果已開啟) 關閉時的值 狀態不明時的值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (預先發布版) true false nil

「isOpenWithRequest」的帳單

  • 系統會針對 GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位收取 Basic Data SKU 費用。其他營業時間則會以「Place Details (進階)」SKU 計費。
  • 如果您的 GMSPlace 物件已包含先前要求中的這些欄位，就不會再向您收費。

範例：提出 GMSPlaceIsOpenWithRequest 要求

以下範例說明如何在現有的 GMSPlace 物件中初始化 GMSPlaceIsOpenWithRequest。

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
          }

必要參數

使用 GMSFetchPlaceRequest 物件指定必要參數。

地點 ID

Places SDK for iOS 使用的地點 ID，與 Places API、Places SDK for Android 和其他 Google API 使用的 ID 相同。每個地點 ID 只能指向一個地點，但一個地點可以有多個地點 ID。

有時地點會取得新的地點 ID。舉例來說，如果商家搬遷至新地點，就可能發生這種情況。

當您透過指定地點 ID 要求地點時，您可以確信在回應中一律會收到相同的地點 (如果地點仍存在的話)。不過請注意，回應中可能包含與要求中不同的地點 ID。

欄位清單

要求地點詳細資料時，您必須在 GMSPlace 物件中指定要以欄位遮罩形式傳回的地點資料。如要定義欄位遮罩，請將 GMSPlaceProperty 的值陣列傳遞至 GMSFetchPlaceRequest 物件。欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，進而避免不必要的處理時間和帳單費用。

指定下列一或多個欄位：

  • 下列欄位會觸發 Place Details (ID Only) SKU：

    GMSPlacePropertyPlaceID、GMSPlacePropertyName、GMSPlacePropertyPhotos

  • 下列欄位會觸發 Place Details (Location Only) SKU：

    GMSPlacePropertyAddressComponents、GMSPlacePropertyFormattedAddress、GMSPlacePropertyCoordinate、GMSPlacePropertyPlusCode、GMSPlacePropertyTypes、GMSPlacePropertyViewport

  • 下列欄位會觸發 Place Details (Basic) SKU：

    GMSPlacePropertyBusinessStatus、GMSPlacePropertyIconBackgroundColor、GMSPlacePropertyIconImageURL、GMSPlacePropertyUTCOffsetMinutes、GMSPlacePropertyWheelchairAccessibleEntrance

  • 下列欄位會觸發 Place Details (Advanced) SKU：

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

  • 下列欄位會觸發 Place Details (Preferred) SKU：

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

以下範例會傳遞兩個欄位值清單，指定要求傳回的 GMSPlace 物件包含 name 和 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];

iOS 版 Places Swift SDK (預先發布版)

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

選用參數

使用 GMSFetchPlaceRequest 物件指定選用參數。

regionCode

用於格式化回應的區域代碼，指定為 兩個字元的 CLDR 代碼值。這個參數也會對搜尋結果產生偏差效果。沒有預設值。

如果回應中的地址欄位國家/地區名稱與區域代碼相符，系統就會從地址中省略國家/地區代碼。

大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼則是「gb」(技術上是「The United Kingdom of Great Britain and Northern Ireland」實體)。這個參數可能會影響根據適用法律產生的結果。

sessionToken

工作階段符記是使用者產生的字串，可將自動完成 (新) 呼叫追蹤為「工作階段」。Autocomplete (New) 會使用工作階段符記，將使用者自動完成搜尋的查詢和地點選取階段歸入不同的工作階段，以用於計費。系統會將工作階段符記傳遞至 Autocomplete (新版) 呼叫後的 Place Details (新版) 呼叫。詳情請參閱「工作階段符記」。

在應用程式中顯示出處資訊

如果應用程式會顯示從 GMSPlacesClient 取得的資訊 (例如相片和評論)，則也必須顯示必要的出處資訊。

舉例來說，GMSPlacesClient 物件的 reviews 屬性包含最多五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件都包含歸屬資訊和作者歸屬資訊。如果您在應用程式中顯示評論，則必須一併顯示任何出處資訊或作者出處資訊。

詳情請參閱歸因說明文件。