選擇 SDK 版本

應用程式提供的 Places SDK for Android 功能是由您在應用程式設定中指定的 SDK 版本號碼 (例如 3.5.0)、

SDK 版本號碼

您在應用程式層級 build.gradle 檔案中指定的 SDK 版本編號,決定應用程式是否可以存取在特定版本中新增的功能。舉例來說,Autocomplete (新版) 僅適用於 SDK 3.5.0 以上版本。

如要進一步瞭解每個 SDK 版本中的異動內容,請參閱 Places SDK for Android 版本資訊

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 功能,請按照下列步驟操作:

  1. 在 Google Cloud 專案中,啟用 Places API 和/或 Places API (新版)。詳情請參閱「啟用 API」相關說明
  2. 在 API 金鑰限制中,啟用 Places API 和/或 Places API (新版)。詳情請參閱「限制 API 金鑰」一節。
  3. 在應用程式層級的 build.gradle 檔案中,指定版本號碼。詳情請參閱安裝相關說明。

  4. 呼叫 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
搜尋附近地點 (新推出) Places API (新推出) initializeWithNewPlacesApiEnabled() 3.5.0
地點相片 (新推出) 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()
地點相片 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 (New) 只會傳回點陣圖圖片的 URI,而Place Photos 則只會傳回點陣圖圖片。
  • Current Place 僅適用於 Places SDK for Android,不適用於 Places SDK for Android (新版)。

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 的應用程式。

新功能

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 回應 (新)

您現在可以使用地點相片 (新增) 傳回圖片點陣圖的 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 (新版) 會將 Places API 的下列類型從表 2 移到 Places API 的資料表 A (新功能)。也就是說,您現在可以在搜尋中使用下列類型:

  • country
  • administrative_area_level_1
  • administrative_area_level_2
  • postal_code
  • locality