總覽

Places API 服務可透過多種方法接受 HTTP 要求,取得位置資料。會傳回有關建築物、地理位置或重要搜尋點的格式化位置資料和圖像。

使用 Places API 的好處

建立位置辨識功能,讓使用者輕鬆取得詳細的位置資料。 透過 Places API 提供的資料,建構在現實世界中最準確、最新的全方位地點模型之一。以下是應用程式用途範例:

  • 在主要大都會區域顯示公寓租賃服務,並提供以城市為指定目標的結果。
  • 在取貨或送貨狀態更新中加入地點詳細資料。
  • 顯示某區域的公園清單,以及使用者提交的相片和評論。
  • 提供使用者規劃行程時,他們會附上建築物的聯絡資訊、評論和價位。

Places API 的用途

您可以使用 Places API,在應用程式中加入下列功能:

  • 提供各類使用者查詢的地點搜尋結果,例如輸入文字、附近地點,以及無法識別或類別的使用者查詢。
  • 為不同的搜尋類型 (特定文字查詢或類別查詢) 啟用自動完成功能。
  • 修正地點傳回的詳細資料類型,例如營業時間、摘要、使用者評論和相片。
  • 將高畫質相片新增至應用程式提供的地點。

許多 Google 地圖平台 API 支援地點 ID,因為地點 ID 可明確識別 Google 地點介面集資料庫和 Google 地圖上的地點。取得地點 ID 的方法很多,包括透過 Places API,以及 Geocoding APIRoutes APIAddress Validation API

取得地點 ID 後,您可以使用 Places API 要求特定建築物或搜尋點的詳細資訊,例如完整地址、電話號碼、使用者評分和評論。

選擇您的 Places API 版本

Places API 支援兩種 API 版本:Places API 是現有的 API,而 Places API (新版) 則是新一代的 API。

隨著 Places API (新版) 推出,第一項工作是決定要使用哪個 API 組合。您是新客戶或已使用 API 的現有客戶。請參閱這份指南,瞭解這兩個 API 之間的主要差異。

Places API 的運作方式

Places API (新推出)

Places API (新版) 會接受要求,當做具有特定服務端點 (例如 /placesplaces:searchText) 的標準網址,然後傳回 JSON 回應。Places API (新版) 支援透過 API 金鑰和 OAuth 權杖進行授權。下例提出 Place Details 要求,以使用 API 金鑰傳回地點 ID 的地址元件:

https://places.googleapis.com/v1/places/GyuEmsRBfy61i59si0?fields=addressComponents&key=YOUR_API_KEY

Places API

Places API 會將要求視為具有特定服務端點 (例如 /place/photo) 的標準網址。端點也會接受要求中指定的格式類型:JSON 或 XML。服務要求會使用與特定端點相關的參數,修正傳回的資料。下例提出 Place Details 要求,以 JSON 格式傳回地點 ID 的地址元件:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&fields=address_components&key=YOUR_API_KEY

在這個範例中,服務會使用提供的地點 ID 尋找要求的地點,並傳回 JSON 格式的地址元件。

資源

下表摘要列出 Places API 提供的資源。

Places API Places API (新推出) 注意事項
Find Place 文字搜尋 (新推出) 「尋找地點」服務沒有新版本。「文字搜尋」(新版) 已取代原本的內容。
搜尋附近 搜尋附近地點 (新推出) 透過含有文字查詢的現有 API 的所有要求,都應使用 Text Search (New),因為 Nearby Search (新) 不支援文字輸入。
搜尋文字 文字搜尋 (新推出)
Place Details Place Details (新推出)
Place Photo Place Photo (新品)
Place Autocomplete 自動完成 (新推出) 預先發布版
查詢自動完成 自動完成 (新推出) 已新增自動完成預先發布版的功能 (新推出)

如何使用 Places API

以下步驟涵蓋使用 Places API 服務的一般應用實例。建構解決方案時,您可以使用其他端點,例如 Nearby Search 和 Place Photos。
1 做好準備 請從「設定 Google Cloud 專案」開始,完成後續的設定操作說明,然後瞭解如何使用 API 金鑰。如果是 Places API (新版),您也可以使用 OAuth 權杖
2 嘗試使用基本文字搜尋 使用文字搜尋 (新推出)文字搜尋來執行簡單的文字搜尋。
3 請使用地點 ID 瞭解詳情 許多 Google 地圖平台 API 都會在回應中傳回地點 ID。使用地點 ID 取得地點詳細資料。請參閱 Place Details (新版)Place Details
4 取得地點的相片 「地點相片」服務可讓您存取數百萬張儲存在地點介面集資料庫的相片。使用 Place Photo (新推出)Place Details 存取地點的相片。