應用程式可用的 Places SDK for Android 功能,取決於您在應用程式設定中指定的 SDK 版本號碼 (例如 3.5.0)、API 金鑰中啟用的 API,以及初始化應用程式的方式。本指南說明各版本的差異,以及如何選取要在應用程式中啟用的版本。
SDK 版本號碼
您在應用程式層級 build.gradle 檔案中指定的 SDK 版本號碼,會決定應用程式是否可存取特定版本中新增的功能。舉例來說,Autocomplete (New) 僅適用於 SDK 3.5.0 以上版本。
如要進一步瞭解各個 SDK 版本中引入的變更,請參閱 Android 版 Places SDK 版本資訊。
Places SDK for Android 的 Places API 版本
除了指定 SDK 版本號碼之外,您還必須選取 SDK 在 Google Cloud 控制台中呼叫的 Places API 服務:Places API 或 Places API (新版)。您選取的 API 服務會與 SDK 版本號碼一同,決定應用程式可使用的特定功能版本,例如 Autocomplete 或 Autocomplete (新版)。雖然您只能指定一個 SDK 版本號碼,但可以同時在 API 金鑰中啟用 Places API 和 Places API (新版),然後透過您用於在應用程式中初始化 SDK 的方法,選取 SDK 呼叫的服務。不過,在大多數情況下,您會想啟用 Places API (新版),並在應用程式中使用 SDK 功能的 (新版)。
選取 SDK 版本和 API 服務
如要選取應用程式可使用的 SDK 功能,請按照下列步驟操作:
- 在 Google Cloud 專案中啟用 Places API、Places API (新版) 或兩者皆可。詳情請參閱「啟用 API」
- 在 API 金鑰限制中,啟用 Places API、Places API (新版),或同時啟用這兩者。詳情請參閱「限制 API 金鑰」。
在應用程式層級的 build.gradle 檔案中指定版本號碼。詳情請參閱「安裝」一節。
呼叫
Places.initializeWithNewPlacesApiEnabled()
或Places.initialize()
方法,初始化應用程式。
如要進一步瞭解如何選取 Places API 服務,請參閱「設定 Google Cloud 專案」。
各個版本提供的 SDK 功能
下表列出各項 SDK 功能所需的 SDK 和 API 版本:
功能 | 在 API 金鑰中啟用 Places API | 初始化方法 | 最低 SDK 版本 |
---|---|---|---|
自動完成 (新功能) | Places API (新推出) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
Place Details (新版) | Places API (新推出) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
Nearby Search (新版) | Places API (新推出) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
Place Photos (新版) | Places API (新推出) | initializeWithNewPlacesApiEnabled() |
3.4.0 |
文字搜尋 (新版) | Places API (新推出) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
Place Autocomplete | Places API | initialize() |
|
目前所在地點 | Places API | initialize() |
|
Place Details | Places API | initialize() |
|
Place Photos | Places API | initialize() |
選擇要啟用哪些版本的考量因素
如要決定要選擇哪個版本,請考量以下因素:
- 如果您是新客戶,剛開始使用 Places SDK for Android,請先使用 Places API (新版) 和新版 SDK。
- 如果您是現有客戶,可以繼續使用現有的 SDK。不過,如要善用 Places SDK for Android (新版) 的效能改善和功能強化功能,您應使用新版 SDK。轉換至新 SDK 時,不需要遷移,只要按照「選取 SDK 版本和 API 服務」中的步驟操作即可。
- 在 Places SDK for Android (新版) 中,您可以從 3.5.0 版開始使用工作階段權杖。詳情請參閱「工作階段符記」。
- 使用 Place Autocomplete 小工具發出的呼叫一律會呼叫 Place Autocomplete,而非 Place Autocomplete (新版);小工具呼叫不會受到初始化方法的影響。
- Place Photos (新版) 只會傳回點陣圖片的 URI,而 Place Photos 只會傳回點陣圖片。
- Current Place 僅適用於 Places SDK for Android,不適用於 Places SDK for Android (新版)。
Places SDK for Android 的強化功能 (新功能)
本節將介紹新增至 Places SDK for Android 的關鍵功能。
在 Google Cloud 標準平台上實作
Places SDK for Android (新版) 已在 Google Cloud 的服務基礎架構上實作。這項實作可帶來更安全可靠的平台。這項標準設計可讓 SDK 保持一致,進而提升使用 Places SDK for Android (新版) 的開發效率。
提高效能
Places SDK for Android (新版) 可提供更佳的效能,因此值得您更換使用現有 SDK 的應用程式。
新功能
Places SDK for Android (新版) 包含所有 SDK 功能的最新版本:
新版文字搜尋服務
Text Search (新版) 可根據字串 (例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」),傳回一組地點的相關資訊。這項服務會傳回與文字字串和任何位置自訂調整設定相符的地點清單。
新增回應資料至 Place Details (新版) 和 Place Photos (新版)
Place Details (新版) 現在會在回應
Place
物件中加入新的 Review 類別。Place 類別包含新的getReviews()
方法,可支援這個欄位。呼叫getReviews()
即可傳回最多五則地點評論。Place Photo (新功能) 會將
AuthorAttributions
新增至PhotoMetadata
類別。AuthorAttributions
包含AuthorAttribution
物件的List
。
新增 URI 回應至 Place Photos (新版)
您現在可以使用 Place Photo (新功能) 傳回圖片點陣圖的 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 |
顧問 | 直升機停機坪 | 遊樂場 | 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 | 飯店 | rest_stop |
除了這些新類型外,Places API (新版) 也將下列類型從 Places API 的 Table 2 移至 Places API (新版) 的 Table A。也就是說,您現在可以使用這些類型做為搜尋的一部分:
country
administrative_area_level_1
administrative_area_level_2
postal_code
locality