Place Details (最新)

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

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

取得 Place Details

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

GMSFetchPlaceRequest 物件會指定：

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

提出 Place Details 要求

本範例透過 ID 取得地點，並傳遞下列參數：

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

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

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

GooglePlacesSwift

// 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 物件。

除了資料欄位，回應中的 GMSPlace 物件還包含下列成員函式：

  • isOpen 會計算地點在特定時間是否營業中。
  • isOpenAtDate 會計算地點在特定日期是否營業。

必要參數

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

地點 ID

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

在某些情況下，地點可能會取得新的地點 ID。舉例來說，假設商家搬遷至新地點，就可能發生這種情況。

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

欄位清單

要求 Place Details 時，您必須指定要在地點的 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];

GooglePlacesSwift

// 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」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律，這個參數可能會影響結果。

sessionToken

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

在應用程式中顯示作者資訊

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

例如，GMSPlacesClient 物件的 reviews 屬性包含最多五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件皆可包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論，則您也必須顯示所有作者資訊或作者作者資訊。

如需更多資訊，請參閱歸因說明文件。