本頁面由 Cloud Translation API 翻譯而成。

選擇 SDK 版本

Places SDK for Android 3.4.0 版支援兩個 SDK 版本：Places SDK for Android 是現有 SDK，Places SDK for Android (新版) 則是新一代的 SDK。

推出 Places SDK for Android 3.4.0 後，第一項工作就是決定要使用的 SDK。如果您是新客戶或已使用 SDK 的現有客戶，就屬於這種情況。請參閱本指南，瞭解這兩個 SDK 之間的主要差異。

如何選取 SDK 版本

在後端，Places SDK for Android 需要使用 Places API (新版) 或 Places API。您必須先在 Google Cloud 專案中啟用 Places API 服務，才能使用 Places SDK for Android。

針對 Android，您可以採取兩項操作來決定應用程式可使用哪些 API：

在專案中，您必須根據要在應用程式中使用的項目，為 API 金鑰啟用 Places API (新版) 和/或 Places API。
呼叫 Places.initializeWithNewPlacesApiEnabled() 或 Places.initialize() 方法，藉此初始化應用程式。

選取 SDK

啟用控制應用程式所用 SDK 版本的 Places API 服務版本：

兩者：啟用 Places SDK for Android 和 Places SDK for Android (New) 的所有功能。請使用 Places.initializeWithNewPlacesApiEnabled() 和 Places.initialize() 方法控管可用的功能。
Places API：啟用現有的 Places SDK for Android。您無法使用 Places SDK for Android 3.4.0 版新增的功能。
Places API (新版)：啟用 Places SDK for Android (新版) 和「新增至 Places SDK for Android (新版) 的主要功能」一文所述的所有新功能，但不會啟用現有功能，例如「目前地點」和「地點自動完成」。

如要進一步瞭解如何選取 Places API 服務，請參閱「設定 Google Cloud 專案」一文。

初始化應用程式

初始化應用程式時，您必須呼叫 Places.initializeWithNewPlacesApiEnabled() 或 Places.initialize() 方法。

下表顯示啟用每個 SDK 並呼叫每個初始化方法的影響。舉例來說，如果啟用 Places SDK (新版) 並呼叫 Places.initializeWithNewPlacesApiEnabled()，就能使用所有新 API 和現有 API。

如果您啟用 Places SDK (新版) 並呼叫 Places.initialize()，就無法使用 Place Details 和 Place Photos 的新功能，但可以呼叫新的 Text Search。如果不啟用 Places API，就無法存取舊版 Place Details，但仍可呼叫新版 Text Search。

版本	API	已為 API 金鑰啟用 SDK		初始化方法
		Places API	Places API (新推出)	`initialize()`	`initializeWithNewPlacesApiEnabled()`
v3.3.0	Places Details
	地點詳細資料 (新功能)
	相片中繼資料 (新推出)
	Text Search (新版)			兩者皆可
v3.4.0	相片 URI (新品)
	相片點陣圖			兩者皆可
	CurrentPlace			兩者皆可
	自動完成			兩者皆可

您選用哪一種 SDK？

如何決定要選擇的版本：

如果您是剛開始使用 Places SDK for Android 的新客戶，請先使用 Places API (新版) 和新版 SDK。
如果您是 Kotlin 開發人員，可以使用任一 SDK，但 Places SDK for Android (新版) 中的新功能僅適用於 3.4.0 版中的 Java。
如果您是現有客戶，且正在使用工作階段符記，請繼續使用現有的 SDK。Places SDK for Android (新版) 目前不支援工作階段符記。
如果您是現有客戶，可以繼續使用現有的 SDK。不過，如要享有 Places SDK for Android (新版) 的效能改善項目和功能強化功能，建議您使用新版 SDK。

改用新版 SDK 時不需要進行遷移。您只需要執行以下作業：
1. 針對應用程式中使用的 API 金鑰啟用 Places API (新版)。詳情請參閱「使用 API 金鑰」一文。
2. 在模組層級 build.gradle 檔案的 dependencies 區段中，更新 places 依附元件並新增 kotlin-bom 依附元件：
```
  dependencies {
      implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
      implementation 'com.google.android.libraries.places:places:3.3.0'
  }
```
  如要進一步瞭解 kotlin-bom 依附元件，請參閱遞移依附元件中使用最新的 kotlin-stdlib 版本相關說明。
3. 更新現有應用程式，以呼叫新的 Places.initializeWithNewPlacesApiEnabled() 方法，以便初始化應用程式。詳情請參閱「初始化 Places API 用戶端」。
現有應用程式會繼續運作，但現在可以善加利用所有新的 SDK 功能。

Places SDK for Android 新增的重要功能 (新)

本節說明 Places SDK for Android (新版) 的重要功能。

已在 Google Cloud Standard 平台上實作

Places SDK for Android (新版) 已導入 Google Cloud 的服務基礎架構。實作可提供更加安全可靠的平台。這個標準設計可讓所有 SDK 各具一致性，提高 Places SDK for Android 的開發效率 (新品)。

提高效能

Places SDK for Android (新版) 可提升效能，因此建議您替換使用現有 SDK 的應用程式。

新的文字搜尋服務

Text Search 可根據字串 (例如「臺北披薩」、「臺北披薩店」或「中正路 123 號」) 傳回一組地點的相關資訊。這項服務會傳回與文字字串和位置自訂調整設定相符的地點清單。

已在 Placed Details 和 Place Photos 中新增回應資料

Place Details 現已在回應 Place 物件中加入新的 Review 類別。Place 類別包含用於支援這個欄位的新 getReviews() 方法。呼叫 getReviews() 可傳回特定地點的評論 (最多 5 則)。
Place Photo 會將 AuthorAttributions 新增至 PhotoMetadata 類別。AuthorAttributions 包含 AuthorAttribution 物件的 List。

已在 Place Photos 中新增 URI 回應

您現在可以使用 Place Photos 傳回圖片點陣圖的 URI。先前您只能傳回圖片點陣圖本身。

簡化計費模式

Places SDK for Android (新版) 簡化了定價作業，因此您只需要為實際使用的資料付費。簡化定價的實作方式是使用欄位清單 (也稱為「欄位遮罩」)。

透過 Place Details 和 Text Search，您可以使用欄位清單控管回應中要傳回的欄位清單。如此一來，您只需為所要求的資料付費。使用欄位清單是不錯的設計做法，可避免要求不必要的資料，避免不必要的處理時間和帳單費用。

如需這兩種 SDK 的詳細定價資訊，請參閱「用量與計費」一文。

展開的地點類型

新版 SDK 會新增下表顯示的地點類型。這些類型會做為 Place Details 和 Text Search 回應的一部分傳回。您也可以使用這些新類型和現有類型，透過文字搜尋進行搜尋。新類型已包含在表 A 中。

類型
american_restaurant	discount_store	ice_cream_shop	sandwich_shop
amusement_center	dog_park	indian_restaurant	school_district
athletic_field	electric_vehicle_charging_station	indonesian_restaurant	seafood_restaurant
auto_parts_store	event_venue	italian_restaurant	ski_resort
banquet_hall	extended_stay_hotel	japanese_restaurant	spanish_restaurant
barbecue_restaurant	設備	korean_restaurant	sporting_goods_store
barber_shop	Farmstay	lebanese_restaurant	sports_club
bed_and_breakfast	fast_food_restaurant	Marina	sports_complex
brazilian_restaurant	ferry_terminal	市場	steak_house
breakfast_restaurant	fitness_center	medical_lab	sushi_restaurant
brunch_restaurant	french_restaurant	mediterranean_restaurant	swimming_pool
bus_stop	gift_shop	mexican_restaurant	量身訂製
camping_cabin	golf_course	middle_eastern_restaurant	telecommunications_service_provider
cell_phone_store	greek_restaurant	汽車旅館	thai_restaurant
child_care_agency	grocery_store	national_park	transit_depot
chinese_restaurant	guest_house	park_and_ride	truck_stop
coffee_shop	hair_salon	performing_arts_theater	turkish_restaurant
community_center	hamburger_restaurant	pizza_restaurant	vegan_restaurant
顧問	Heliport	playground	vegetarian_restaurant
convention_center	hiking_area	學齡前幼童	vietnamese_restaurant
木屋	historical_landmark	private_guest_room	visitor_center
courier_service	home_improvement_store	ramen_restaurant	wedding_venue
cultural_center	青年旅館	resort_hotel	批發商
dental_clinic	hotel	rest_stop

除了這些新類型外，Places API (新版) 已從資料表 B 中移除下列類型。也就是說，現在您可以在搜尋中使用下列類型：

country
administrative_area_level_1
administrative_area_level_2
postal_code
locality