Places API (舊版) 快速參考

2026 年 10 月起,新的 Google Cloud 雲端專案將無法再啟用 Places API (舊版)。現有專案仍可正常運作。如要使用新功能並提升效能,請改用 Places API (新版)。

Places API (舊版):重要資訊

  • 產品:Places API (舊版)
  • 別名:Places API (舊版網路服務)、Places API 網路服務 (maps/api/place)
  • 類別:地點
  • 平台:網路服務 (REST)
  • 執行位置:伺服器 (後端程式碼)
  • 推出階段:GA
  • 生命週期:舊版
  • 取代為:Places API (新版)
  • 總覽:Places API (舊版) 總覽

Places API (舊版):使用時機

在下列情況下使用 Places API (舊版):

  • 您維護的現有專案已啟用 Places API (舊版),並呼叫 maps.googleapis.com/maps/api/place 端點。
  • 您需要現有的 Find Place、Nearby Search、Text Search、Details、Photos 或 Autocomplete (舊版) 呼叫,才能在遷移期間繼續運作。

請勿在下列情況使用 Places API (舊版):

  • 您要建立新的 Google Cloud 專案。自 2026 年 10 月起,新專案將無法啟用 Places API (舊版)。請改用 Places API (新版)。
  • 您需要 Nearby Search 和 Text Search 的新功能、OAuth 驗證或欄位遮罩,因此只需為要求的欄位付費。請改用 Places API (新版)。
  • 您需要在新程式碼中使用 Find Place (舊版) 或 Query Autocomplete (舊版)。並由 Text Search (新版) 和 Autocomplete (新版) 取代。請改用 Places API (新版)。

Places API (舊版):設定

Places API (舊版):常見錯誤

  • 問題:如果 Place Details (舊版) 要求省略 fields 參數或未指定任何欄位,API 會傳回所有欄位,並向您收取所有欄位的費用。修正方式:請務必設定 fields 參數,或使用欄位遮罩遷移至 Place Details (新版)。請參閱 /maps/documentation/places/web-service/legacy/details。
  • 問題:Nearby Search (舊版) 和 Text Search (舊版) 不支援指定要傳回的欄位。這類要求一律會傳回一組固定的欄位 (Place Details 欄位的子集),並觸發 Basic Data、Contact Data 和 Atmosphere Data SKU。修正方式:改用 Nearby Search (新版) 或 Text Search (新版) 並搭配欄位遮罩,或使用 Find Place (舊版) 並搭配 fields 參數,只要求所需欄位並支付相關費用。請參閱 /maps/billing-and-pricing/sku-details/legacy#places_nearby-search-legacy-pro-sku。
  • 問題:photo_reference 無法快取,且可能會過期,因此儲存的參照會停止運作。修正方式:先從 Place Details、Find Place、Nearby Search 或 Text Search 回應中取得新的 photo_reference,再要求相片。請參閱 /maps/documentation/places/web-service/legacy/photos。
  • 問題:如果專案未啟用 Places API (舊版),呼叫該 API 時會傳回 REQUEST_DENIED,並顯示錯誤訊息「您呼叫的舊版 API 未在專案中啟用...」LegacyApiNotActivatedMapError。2026 年 10 月起,新專案將無法啟用 Places API (舊版)。修正方式:新專案請使用 Places API (新版),並遷移現有應用程式。遷移期間,您可以透過舊版頁面的意見回饋表單,要求短期啟用舊版 API。請參閱 /maps/legacy#LegacyApiNotActivatedMapError。

Places API (舊版):舊版和已淘汰的功能

  • permanently_closed 回應欄位:自 2020 年 5 月 26 日起淘汰。替代項目:business_status 欄位。請參閱遷移指南。
  • reference 回應欄位:已於 2019 年 9 月 3 日淘汰。替代項目:place_id 欄位。請參閱遷移指南。
  • Nearby Search (舊版) name 要求參數:已淘汰。替代項目:keyword 參數。請參閱遷移指南。