Places API (新版) 是一項網路服務,可傳回商家、地理位置和搜尋點的 JSON 位置資料。支援 Text Search (新版)、Nearby Search (新版)、Autocomplete (新版)、Place Details (新版) 和 Place Photos (新版)。
Places API (新版):重要資訊
- 產品:Places API (新版)
- 別名:Places API
- 類別:地點
- 平台:網路服務 (REST)
- 執行位置:伺服器 (後端程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Places API (新版) 總覽
- 適用地區:全球。帳單地址位於歐洲經濟區的專案,須遵守 Google Maps Platform 歐洲經濟區服務條款 (2025 年 7 月 8 日生效),其中規定 Places API 內容 (經緯度和地點 ID 除外) 只能透過 Places UI Kit 搭配地圖使用。AI 輔助的地點、評論和區域摘要功能,僅適用於支援的語言和區域。
Places API (新版):使用時機
在下列情況下使用 Places API (新版):
- 您需要透過文字查詢 (Text Search (新版)) 或在某個位置附近 (Nearby Search (新版)),從伺服器搜尋地點。
- 您需要透過 Autocomplete (新版),從後端取得預測查詢字串或地點。
- 您有地點 ID,需要地址、電話號碼、評分、評論或相片等詳細資料。
- 您需要 AI 輔助的地點、評論或區域摘要。
不適合使用 Places API (新版) 的情況:
- 您正在建構原生 Android 應用程式。請改用 Places SDK for Android。
- 您正在建構原生 iOS 應用程式。請改用 Places SDK for iOS。
- 您正在建構瀏覽器網頁應用程式,並想在 JavaScript 中載入 Places Library。請改用 Maps JavaScript API。
Places API (新版):設定
- 要啟用的服務:
places.googleapis.com - 驗證:API 金鑰、OAuth 2.0
- 開始使用:設定 Places API (新版)
- 參考資料:Places API (新版) 參考資料
- 定價:Places API (新版) 用量與計費
- 政策:Places API (新版) 政策
- 版本資訊:Places API (新版) 版本資訊
官方 Places API (新版) 套件:
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API (新版):相關產品
- 取代:Places API (舊版)
- 常搭配使用的 API:Geocoding API、Routes API、Address Validation API
Places API (新版):常見錯誤
- 問題:Place Details (新版)、Nearby Search (新版) 和 Text Search (新版) 沒有預設的傳回欄位清單;如果要求未提供欄位遮罩,就會傳回錯誤。修正方式:使用
fields或$fields參數,或X-Goog-FieldMask標頭傳遞回應欄位遮罩。請參閱 /maps/documentation/places/web-service/choose-fields。 - 問題:如果省略 Autocomplete (新版) 工作階段符記,或在工作階段結束後重複使用,系統會以 SKU:Autocomplete Requests 分別向每項要求收費。修正方式:為每個工作階段產生新的工作階段符記 (建議使用 UUID v4),並以 Place Details (新版) 或地址驗證要求結束工作階段。詳情請參閱 /maps/documentation/places/web-service/place-session-tokens。
- 問題:現有或 AI 生成的程式碼,在未啟用舊版 API 的專案中呼叫 Places API (舊版) 或 Maps JavaScript API
PlacesService,導致LegacyApiNotActivatedMapError失敗。修正方式:將呼叫遷移至 Places API (新版),並加入必要的欄位遮罩。請參閱 /maps/legacy#LegacyApiNotActivatedMapError。 - 問題:儲存的地點 ID 可能會過時,導致 Place Details (新版) 傳回
NOT_FOUND(HTTP 404),格式錯誤或截斷的 ID 則傳回 HTTP 400INVALID_ARGUMENT。修正方式:使用 Place Details (New) 要求,重新整理儲存超過 12 個月的地點 ID,並只要求id欄位 (免付費)。詳情請參閱 /maps/documentation/places/web-service/place-id#refresh-id。
Places API (新版) 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
Places API (新版):生成式 AI
Places API (新版):地點
- 根據查詢字串傳回地點清單和 Place Details。
- 傳回特定位置附近的地點和地點詳細資料清單。
- 根據查詢字串,傳回地點的自動完成結果。
- 傳回特定地點的詳細資訊。
- 傳回特定地點的相片。注意:請在相片旁顯示每張相片的作者資訊 (作者姓名,並連結至其個人資料 URI)。各平台的 Places 政策都有這項規定,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 調整地點相片大小。
- 傳回特定地點的評分和評論。注意:在 Places API (新版) Web 服務中,Place Details 是向 https://places.googleapis.com/v1/places/{placeId} 傳送的 HTTP GET 要求,並包含 X-Goog-FieldMask (例如 rating、userRatingCount、reviews);Text Search、Nearby Search 和 Autocomplete 則使用 POST。在 Android 上,將 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 傳遞至 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中傳遞 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 指定地點資訊回應中包含的資料欄位。
- 指定要在地點資訊回應中包含的地點類型。
- 傳回 URI,在 Google 地圖中開啟地點的 Place Details 頁面。
- 傳回 URI,在 Google 地圖中開啟地點的路線頁面。
- 傳回 URI,在 Google 地圖中開啟地點的「撰寫評論」頁面。
- 傳回 URI,在 Google 地圖中開啟地點的評論頁面。
- 傳回 URI,在 Google 地圖中開啟地點的相片頁面。
- 傳回特定地點的 AI 生成摘要。
- 傳回 AI 輔助的區域摘要,說明特定地點周遭區域的地點。
- 根據查詢字串,傳回預先定義路線上的地點資訊。
- 根據一組經緯度座標,傳回距離、行程時間和路線 URI,以便透過 Text Search 搜尋地點。
- 根據一組經緯度座標,傳回附近地點的距離、行程時間和路線 URI。
- 傳回預先定義路線起點與各個地點之間的距離、行程時間和路線 URI。這些地點是根據查詢字串傳回,且位於路線上。
- 根據查詢字串,傳回各個地點之間的距離、行程時間和路線 URI,這些地點也位於預先定義的路線和路線目的地。