Places API (新版) 快速參考

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 (新版) 的情況:

Places API (新版):設定

官方 Places API (新版) 套件:

  • npm:@googlemaps/places
  • pypi:google-maps-places
  • go:cloud.google.com/go/maps

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 400 INVALID_ARGUMENT。修正方式:使用 Place Details (New) 要求,重新整理儲存超過 12 個月的地點 ID,並只要求 id 欄位 (免付費)。詳情請參閱 /maps/documentation/places/web-service/place-id#refresh-id。

Places API (新版) 的用途

請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。

Places API (新版):生成式 AI

Places API (新版):地點