遷移作業總覽

本指南會說明舊版 Places 服務與新版 Place 類別之間的主要差異。升級至 Place 類別可帶來多項重要優勢，包括改善效能和採用新的定價模式。如要充分運用 Places，並確保應用程式保持最新狀態，請熟悉本指南中詳述的變更。

遷移作業的帳單最佳做法

如果您的 API 用量足以進入第二級定價，就適用這項指南。遷移至較新版本的 API 時，您也會被收取其他 SKU 的費用。為避免在轉換期間增加費用，建議您盡可能在月初切換至實際執行環境中的新 API。這樣一來，您就能在遷移月份達到最划算的每月定價層級。如要瞭解價格等級，請參閱定價頁面和定價常見問題。

啟用 Places API

Place 類別會依賴 Places API 服務。如要使用新 Place 類別的功能，您必須先在 Google Cloud 專案中啟用 Places API (新版)。詳情請參閱入門指南。

一般變更

下表列出 PlacesService 和 Place 之間的一些主要差異：

PlacesService (舊版) Place (新版)
方法必須使用回呼來處理結果物件和 google.maps.places.PlacesServiceStatus 回應。 使用 Promise，並以非同步方式運作。
方法需要 PlacesServiceStatus 檢查。 不需要進行狀態檢查，可以使用標準錯誤處理。
地點資料欄位的格式為蛇形命名法。 Place 資料欄位的格式為駝峰式大小寫。
僅限於固定的地點類型和地點資料欄位。 提供定期更新的地點類型和地點資料欄位的擴充選項。

API 專屬變更

「地點」類別提供 API，方便您使用 Places 程式庫，並支援 Promise 等新型使用模式。Place 類別會公開與舊版 Places Service 相同的地點資料欄位和地點類型，並包含許多地點資料欄位和地點類型的新值。

下表說明 Places 服務的功能與 Place 類別的功能對應方式：

地點介面集服務 (舊版) 地點類別 (新版)
地點資料欄位 地點類別資料欄位
地點類型 地點類型
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
Autocomplete 類別 PlaceAutocompleteElement 類別
SearchBox 類別 ---

載入 Places 程式庫

應用程式載入 Places 程式庫的方式取決於使用的 Bootstrap 載入器。如果應用程式使用動態程式庫匯入，您可以在執行階段載入所需的程式庫，方法是使用 await 運算子呼叫 importLibrary()，如下所示：

const { Place } = await google.maps.importLibrary("places");

如果您的應用程式使用直接指令碼載入標記，請在載入器指令碼中要求 places 程式庫：

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

如要進一步瞭解如何載入 Maps JavaScript API，請參閱本文。

本節提供以下指南，協助您將應用程式遷移至使用最新版本的 Places API：