您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Places API Web Service

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Places API Web Service
  3. 建立適當的金鑰
繼續

地點搜尋

Google Places API Web Service 可讓您依據各種類別查詢地點資訊,例如:機構、高知名度搜尋點、地理位置等類別。您可以依據鄰近性或文字字串搜尋地點。「地點搜尋」會傳回地點清單以及每個地點的相關摘要資訊;透過地點詳細資料查詢還可取得其他資訊。

附近地點搜尋要求

舊版 Places API 將「附近地點搜尋」稱為「地點搜尋」。

「附近地點搜尋」可讓您搜尋指定區域內的地點。您可以提供關鍵字或指定要搜尋的地點類型,來縮小搜尋要求的範圍。

「附近地點搜尋」要求是具有下列格式的 HTTP URL:

https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters

其中 output 可以是下列任何一個值:

  • json (建議)指出以 JavaScript 物件標記法 (JSON) 格式輸出
  • xml 指出以 XML 格式輸出

某些參數是起始「附近地點搜尋」要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。

必要參數

  • key - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓您的應用程式能夠立即使用從您的應用程式新增的地點。如需詳細資訊,請參閱取得金鑰
  • location - 用來擷取其周圍地點資訊的緯度/經度。這必須以「緯度,經度」的方式指定。
  • radius - 定義要傳回地點結果的距離範圍(單位為公尺)。允許的最大半徑是 50,000 公尺。請注意,如果已指定 rankby=distance (參見下方選擇性參數下的說明),就不得包括 radius
  • 如果已指定 rankby=distance (參見下方選擇性參數下的說明),則必須指定 keywordnametype 其中之一。

選擇性參數

  • keyword - 要與 Google 已為此地點建立索引的所有內容(包括但不限於名稱、類型和地址)比對,以及與客戶評論和其他第三方內容比對的字詞。
  • language - 語言代碼,指出應該以哪一種語言傳回結果(如果可能的話)。搜尋也會偏向所選的語言;使得所選語言會獲得較高的排名。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。
  • minpricemaxprice (選擇性) - 將結果限制在指定範圍內的地點。有效值的範圍是 0(最負擔得起)到 4(最昂貴),含 0 和 4。特定值所代表的確切金額將因地區而異。
  • name — 一個將與 Google 已為此地點建立索引的所有內容相匹配的詞語。等同於 keywordname 欄位已不再限於地點名稱。此欄位中的值會與 keyword 欄位中的值合併,並做為相同搜尋字串的一部分傳遞。我們建議針對所有搜尋字詞僅使用 keyword 參數。
  • opennow - 只傳回傳送查詢時還在營業的地點。如果您在查詢中包括此參數,將不會傳回「Google 地方資訊」資料庫中未指定營業時間的地點。
  • rankby - 指定列出結果的順序。請注意,如果已指定 radius (參見上文必要參數),則不應該包含 rankby。可能的值包括:
    • prominence (預設)。此選項會根據結果的重要性進行排序。排名會以指定區域內的高知名度地點為優先。知名度會受到地點在 Google 索引中的排名、全球熱門度及其他因素影響。
    • distance。此選項會依據與所指定 location 的距離,以遞增順序將搜尋結果排序。已指定 distance 時,必須指定 keywordnametype 其中一或多個參數。
  • type - 將結果限制在與指定類型相符的地點。只能指定一種類型(如果超過一種類型,第一個項目之後的所有類型都會被忽略)。請參閱支援的類型清單
  • types已淘汰) - 將結果限制在至少與其中一個指定類型相符的地點。以直立線符號分隔類型,例如:
    type1|type2|etc
  • pagetoken - 傳回上次執行之搜尋的接下來 20 個結果。設定 pagetoken 參數將會使用與先前使用的相同參數來執行搜尋,pagetoken 以外的所有參數都將被忽略。
  • zagatselected已淘汰) - 新增此參數(只需參數名稱,不需要任何關聯的值)可將您的搜尋限制在 Zagat 評選商家所在的位置。此參數不得包括 truefalse 值。zagatselected 參數是實驗性的,僅供具有 Premium Plan 授權的 Google Places API 客戶使用。

Google Maps API 進階方案 客戶注意事項:您必須在您的要求中包含 API 金鑰。您的要求應該包含 clientsignature 參數。

附近地點搜尋範例



下列範例是要求搜尋澳洲雪梨某地點半徑 500 公尺內,屬於「餐廳」類型且包含搜索 'cruise' 的地點:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

注意:在此範例中,您必須以您自己的 API 金鑰取代 key,才能讓此要求在您的應用程式中運作。

文字搜尋要求

「Google Places API 文字搜尋服務」是一個 Web 服務,此服務會根據字串(例如 "pizza in New York" 或 "shoe stores near Ottawa" 或 "123 Main Street")傳回一組地點的相關資訊。此服務會以與文字字串及任何已設定之位置偏向相符的地點清單做為回應。

此功能在自動化系統中進行模糊地址查詢時特別實用,而且字串的非地址元件可比對商家及地址。模糊地址查詢的例子包括不完整的地址、格式錯誤的地址,包含非地址元件(例如商家名稱)的要求。

搜尋回應將包含地點的清單。您可以傳送「地點詳細資料」要求,以取得回應中任何地點的相關詳細資訊。

「Google 地方資訊」搜尋服務共用相同的使用限制。然而,「文字搜尋」服務會乘上 10 倍。也就是說,您所發出的每個「文字搜尋」要求都會對照您的配額計算為 10 個要求。如果您已經隨著 Google Maps API 進階方案 合約購買 Google Places API,乘數可能會有不同。請參閱 Google Maps API 進階方案 文件以取得詳細資料。

「文字搜尋」要求是具有下列格式的 HTTP URL:

https://maps.googleapis.com/maps/api/place/textsearch/output?parameters

其中 output 可以是下列任何一個值:

  • json (建議)指出以 JavaScript 物件標記法 (JSON) 格式輸出
  • xml 指出以 XML 格式輸出

某些參數是起始搜尋要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。

必要參數

  • query - 做為搜尋依據的文字字串,例如:"restaurant" 或 "123 Main Street"。「Google 地方資訊」服務將會依據此字串傳回相符的候選項目,並依據所感知的結果相關性排列結果順序。如果搜尋要求中也使用 type 參數,則此參數會成為選用參數。
  • key - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓您的應用程式能夠立即使用從您的應用程式新增的地點。請參閱取得 Google Places API Web Service 的金鑰,了解如何建立 API 專案及取得金鑰。

選擇性參數

  • location - 用來擷取其周圍地點資訊的緯度/經度。這必須以「緯度,經度」的方式指定。如果您指定 location 參數,就必須一併指定 radius 參數。
  • radius - 定義地點結果偏向的距離範圍(單位為公尺)。允許的最大半徑是 50,000 公尺。此地區內的結果在排名上會高於搜尋範圍外的結果;不過,在搜尋半徑外的高知名度結果可能會包含在內。
  • language - 語言代碼,指出應該以哪一種語言傳回結果(如果可能的話)。搜尋也會偏向所選的語言;使得所選語言會獲得較高的排名。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。
  • minpricemaxprice (選擇性)- 將結果限制在指定價格等級內的地點。有效值的範圍是 0 (最負擔得起)到 4 (最昂貴),含 0 和 4。特定值所代表的確切金額將因地區而異。
  • opennow - 只傳回傳送查詢時還在營業的地點。如果您在查詢中包括此參數,將不會傳回「Google 地方資訊」資料庫中未指定營業時間的地點。
  • pagetoken - 傳回上次執行之搜尋的接下來 20 個結果。設定 pagetoken 參數將會使用與先前使用的相同參數來執行搜尋,pagetoken 以外的所有參數都將被忽略。
  • type - 將結果限制在與指定類型相符的地點。只能指定一種類型(如果超過一種類型,第一個項目之後的所有類型都會被忽略)。請參閱支援的類型清單
  • types已淘汰) - 將結果限制在至少與其中一個指定類型相符的地點。以直立線符號分隔類型 (type1|type2|etc)。
  • zagatselected已淘汰) - 新增此參數(只需參數名稱,不需要任何關聯的值)可將您的搜尋限制在 Zagat 評選商家所在的位置。此參數不得包括 truefalse 值。zagatselected 參數是實驗性的,僅供具有 Premium Plan 授權的 Google Places API 客戶使用。

您可以透過傳遞 locationradius 參數,將結果偏向指定的圓形範圍。這會將「Google 地方資訊」服務引導成偏好顯示該範圍內的結果。該定義區域外的結果仍然會顯示。

Google Maps API 進階方案 客戶注意事項:您必須在您的要求中包含 API 金鑰。您的要求應該包含 clientsignature 參數。

文字搜尋範例

注意:在這些範例中,您必須以您自己的 API 金鑰取代 key,才能讓此要求在您的應用程式中運作。

範例 1:下列範例顯示搜尋雪梨附近的餐廳。

https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&key=YOUR_API_KEY

範例 2:下列範例顯示搜尋不完整的地址,在此例中,是一個不包括城市或洲或國家的街道地址。

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&key=YOUR_API_KEY

範例 3:下列範例顯示搜尋與範例 2 相同的不完整地址,並包括 locationradius 參數,使結果偏向感興趣的區域。比較範例 2 與範例 3 的結果。

https://maps.googleapis.com/maps/api/place/textsearch/json?query=123+main+street&location=42.3675294,-71.186966&radius=10000&key=YOUR_API_KEY

雷達搜尋要求

「Google Places API 雷達搜尋服務」可讓您一次搜尋高達 200 個地點,但是與一般從「文字搜尋」或「附近地點搜尋」要求傳回的資訊相比較不詳細。您可以使用「雷達搜尋」來建立可協助使用者識別地理區域內特定感興趣區域的應用程式。

搜尋回應最多將包括 200 個地點,而且只會包含每個地點的下列相關資訊:

  • 包含地理座標的 geometry 欄位。
  • place_id,可供您在「地點詳細資料」要求中用來取得地點的詳細資訊。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • 已過時的 reference 欄位。請參閱此頁面上的過時通知

「雷達搜尋」要求是具有下列格式的 HTTP URL:

https://maps.googleapis.com/maps/api/place/radarsearch/output?parameters

其中 output 可以是下列任何一個值:

  • json (建議)指出以 JavaScript 物件標記法 (JSON) 格式輸出
  • xml 指出以 XML 格式輸出

某些參數是起始搜尋要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。

必要參數

  • key - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓您的應用程式能夠立即使用從您的應用程式新增的地點。請參閱取得 Google Places API Web Service 的金鑰,了解如何建立 API 專案及取得金鑰。
  • location - 用來擷取其周圍地點資訊的緯度/經度。這必須以「緯度,經度」的方式指定。
  • radius - 定義要傳回地點結果的距離範圍(單位為公尺)。允許的最大半徑是 50,000 公尺。
  • 「雷達搜尋」要求必須至少包括 keywordnametype 其中之一。

選擇性參數

  • keyword - 要與 Google 已為此地點建立索引的所有內容(包括但不限於名稱、類型和地址)比對,以及與客戶評論和其他第三方內容比對的字詞。
  • language - 語言代碼,指出應該以哪一種語言傳回結果(如果可能的話)。搜尋也會偏向所選的語言;使得所選語言會獲得較高的排名。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。
  • minpricemaxprice (選擇性)- 將結果限制在指定價格等級內的地點。有效值的範圍是 0 (最負擔得起)到 4 (最昂貴),含 0 和 4。特定值所代表的確切金額將因地區而異。
  • name — 一個將與 Google 已為此地點建立索引的所有內容相匹配的詞語。等同於 keywordname 欄位已不再限於地點名稱。此欄位中的值會與 keyword 欄位中的值合併,並做為相同搜尋字串的一部分傳遞。我們建議針對所有搜尋字詞僅使用 keyword 參數。
  • opennow - 只傳回傳送查詢時還在營業的地點。如果您在查詢中包括此參數,將不會傳回「Google 地方資訊」資料庫中未指定營業時間的地點。
  • type - 將結果限制在與指定類型相符的地點。只能指定一種類型(如果超過一種類型,第一個項目之後的所有類型都會被忽略)。請參閱支援的類型清單
  • types已淘汰) - 將結果限制在至少與其中一個指定類型相符的地點。以直立線符號分隔類型 (type1|type2|etc)。
  • zagatselected已淘汰) - 新增此參數(只需參數名稱,不需要任何關聯的值)可將您的搜尋限制在 Zagat 評選商家所在的位置。此參數不得包括 truefalse 值。zagatselected 參數是實驗性的,僅供具有 Premium Plan 授權的 Google Places API 客戶使用。

Google Maps API 進階方案 客戶注意事項:您必須在您的要求中包含 API 金鑰。您的要求應該包含 clientsignature 參數。

雷達搜尋範例

注意:在這些範例中,您必須以您自己的 API 金鑰取代 key,才能讓此要求在您的應用程式中運作。

範例 1:下列範例會傳回英國倫敦附近的博物館清單。

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=51.503186,-0.126446&radius=5000&type=museum&key=YOUR_API_KEY

範例 2:使用 keyword、name 和 type 參數的組合,即可執行更精確的查詢。下列範例會顯示位於巴黎且使用者描述為素食類的餐廳和簡餐店。

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=48.859294,2.347589&radius=5000&type=cafe&keyword=vegetarian&key=YOUR_API_KEY

搜尋回應

傳回搜尋回應時,會依照 URL 要求路徑內 output 旗標所指示的格式傳回。

下列範例示範附近地點搜尋回應。「文字搜尋」回應也相似,不同的是它會傳回 formatted_address 而非 vicinity 屬性。「雷達搜尋」如以上所述,只包括有限的欄位。

JSON
{
   "html_attributions" : [],
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870775,
               "lng" : 151.199025
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "21a0b251c9b8392186142c798263e289fe45b4aa",
         "name" : "Rhythmboat Cruises",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 270,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAF-LjFR1ZV93eawe1cU_3QNMCNmaGkowY7CnOf-kcNmPhNnPEG9W979jOuJJ1sGr75rhD5hqKzjD8vbMbSsRnq_Ni3ZIGfY6hKWmsOf3qHKJInkm4h55lzvLAXJVc-Rr4kI9O1tmIblblUpg2oqoq8RIQRMQJhFsTr5s9haxQ07EQHxoUO0ICubVFGYfJiMUPor1GnIWb5i8",
               "width" : 519
            }
         ],
         "place_id" : "ChIJyWEHuEmuEmsRm9hTkapTCrk",
         "scope" : "GOOGLE",
         "alt_ids" : [
            {
               "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
               "scope" : "APP"
            }
         ],
         "reference" : "CoQBdQAAAFSiijw5-cAV68xdf2O18pKIZ0seJh03u9h9wk_lEdG-cP1dWvp_QGS4SNCBMk_fB06YRsfMrNkINtPez22p5lRIlj5ty_HmcNwcl6GZXbD2RdXsVfLYlQwnZQcnu7ihkjZp_2gk1-fWXql3GQ8-1BEGwgCxG-eaSnIJIBPuIpihEhAY1WYdxPvOWsPnb2-nGb6QGhTipN0lgaLpQTnkcMeAIEvCsSa0Ww",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866891,
               "lng" : 151.200814
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "45a27fd8d56c56dc62afc9b49e1d850440d5c403",
         "name" : "Private Charter Sydney Habour Cruise",
         "photos" : [
            {
               "height" : 426,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAL3n0Zu3U6fseyPl8URGKD49aGB2Wka7CKDZfamoGX2ZTLMBYgTUshjr-MXc0_O2BbvlUAZWtQTBHUVZ-5Sxb1-P-VX2Fx0sZF87q-9vUt19VDwQQmAX_mjQe7UWmU5lJGCOXSgxp2fu1b5VR_PF31RIQTKZLfqm8TA1eynnN4M1XShoU8adzJCcOWK0er14h8SqOIDZctvU",
               "width" : 640
            }
         ],
         "place_id" : "ChIJqwS6fjiuEmsRJAMiOY9MSms",
         "scope" : "GOOGLE",
         "reference" : "CpQBhgAAAFN27qR_t5oSDKPUzjQIeQa3lrRpFTm5alW3ZYbMFm8k10ETbISfK9S1nwcJVfrP-bjra7NSPuhaRulxoonSPQklDyB-xGvcJncq6qDXIUQ3hlI-bx4AxYckAOX74LkupHq7bcaREgrSBE-U6GbA1C3U7I-HnweO4IPtztSEcgW09y03v1hgHzL8xSDElmkQtRIQzLbyBfj3e0FhJzABXjM2QBoUE2EnL-DzWrzpgmMEulUBLGrtu2Y",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "Australia"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870943,
               "lng" : 151.190311
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "30bee58f819b6c47bd24151802f25ecf11df8943",
         "name" : "Bucks Party Cruise",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAA48AX5MsHIMiuipON_Lgh97hPiYDFkxx_vnaZQMOcvcQwYN92o33t5RwjRpOue5R47AjfMltntoz71hto40zqo7vFyxhDuuqhAChKGRQ5mdO5jv5CKWlzi182PICiOb37PiBtiFt7lSLe1SedoyrD-xIQD8xqSOaejWejYHCN4Ye2XBoUT3q2IXJQpMkmffJiBNftv8QSwF4",
               "width" : 800
            }
         ],
         "place_id" : "ChIJLfySpTOuEmsRsc_JfJtljdc",
         "scope" : "GOOGLE",
         "reference" : "CoQBdQAAANQSThnTekt-UokiTiX3oUFT6YDfdQJIG0ljlQnkLfWefcKmjxax0xmUpWjmpWdOsScl9zSyBNImmrTO9AE9DnWTdQ2hY7n-OOU4UgCfX7U0TE1Vf7jyODRISbK-u86TBJij0b2i7oUWq2bGr0cQSj8CV97U5q8SJR3AFDYi3ogqEhCMXjNLR1k8fiXTkG2BxGJmGhTqwE8C4grdjvJ0w5UsAVoOH7v8HQ",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "37 Bank St, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867591,
               "lng" : 151.201196
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "a97f9fb468bcd26b68a23072a55af82d4b325e0d",
         "name" : "Australian Cruise Group",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 242,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAABjeoPQ7NUU3pDitV4Vs0BgP1FLhf_iCgStUZUr4ZuNqQnc5k43jbvjKC2hTGM8SrmdJYyOyxRO3D2yutoJwVC4Vp_dzckkjG35L6LfMm5sjrOr6uyOtr2PNCp1xQylx6vhdcpW8yZjBZCvVsjNajLBIQ-z4ttAMIc8EjEZV7LsoFgRoU6OrqxvKCnkJGb9F16W57iIV4LuM",
               "width" : 200
            }
         ],
         "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
         "scope" : "GOOGLE",
         "reference" : "CoQBeQAAAFvf12y8veSQMdIMmAXQmus1zqkgKQ-O2KEX0Kr47rIRTy6HNsyosVl0CjvEBulIu_cujrSOgICdcxNioFDHtAxXBhqeR-8xXtm52Bp0lVwnO3LzLFY3jeo8WrsyIwNE1kQlGuWA4xklpOknHJuRXSQJVheRlYijOHSgsBQ35mOcEhC5IpbpqCMe82yR136087wZGhSziPEbooYkHLn9e5njOTuBprcfVw",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "32 The Promenade, King Street Wharf 5, Sydney"
      }
   ],
   "status" : "OK"
}

JSON 回應最多包含四個根元素:

  • "status" 包含與要求相關的中繼資料。請參閱下方的狀態碼
  • "results" 包含地點陣列與每個地點的相關資訊。請參閱搜尋結果,以取得這些結果的相關資訊。Places API 針對每一查詢最多會傳回 20 個 establishment 結果。此外,還可能傳回 political 結果,這可用來識別要求的區域。
  • html_attributions 包含必須對使用者顯示、關於此清單的一組相關資料引用標示。
  • next_page_token 包含可用來傳回最多 20 個額外結果的語彙基元。如果沒有任何額外的結果可供顯示,將不會傳回 next_page_token。可傳回的結果數目上限為 60。在發出 next_page_token 到它變成有效之間,會有短暫延遲。

請參閱使用 Javascript 處理 JSON,以取得剖析 JSON 回應的說明。

XML
<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Rhythmboat Cruises</name>
  <vicinity>Pyrmont Bay Wharf Darling Dr, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8707750</lat>
    <lng>151.1990250</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJyWEHuEmuEmsRm9hTkapTCrk</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CoQBdAAAAChhtoQX_467esHavS0Sj9DrY306W3_uDXKmB2us8Eh7_dX7rDuln18i_uqocF_LmzRptuFr6WZs7aeBSLFq8VFmckxFjsXDaqMdd3gvxi_5dIwPTEugQQYG9oJA-YnYfPBvjGtuoMfNnjyU2GuxGRmJjCO77pEAbsTLq44eBG5jEhAvkKHCGqIzqgC9tdOb1dSqGhRA1hhG4pvILD5OEAq6W8L8sXbkug</reference>
  <id>21a0b251c9b8392186142c798263e289fe45b4aa</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAiRA8ls6lx5LTfLuHJtLYvz73LXIMa5EVsHz2OUjh70LBPBnIEULZ57w076gOuyCeJqP041_v-ek3I5C4IkqW7YgA0EBybwywfIcUXsj5W_qiJR2yaXHXI-FmDM6j1zaS0sJQnNJhe4Bl9W42Jx16phIQRmNOWKGIemKLgzNEPcCnmBoUGgr0gWQBwWd8HAseR-5ie3JYuIM</photo_reference>
   <width>519</width>
   <height>270</height>
  </photo>
 </result>
 <result>
  <name>Private Charter Sydney Habour Cruise</name>
  <vicinity>Australia</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8668910</lat>
    <lng>151.2008140</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJqwS6fjiuEmsRJAMiOY9MSms</place_id>
  <scope>GOOGLE</scope>
  <reference>CpQBhQAAAKGKrbbnAW3_eAypKW9bhAzAuSmaqAogs7MTFxsntDqCzt-gKD9nz-zqNsk0uJsl0yCUYpNYjHz_yzmh3J_4TTxpxIqdaq2uDvfoTYtvm8FkxMAkK3cS7k9t3Ze2aHRWnxlN9hczK2xlc5taDE7xAGOHF5Xe5IlVV1wV66sOrWrlHtGh47lqT9Id86eG2OmlVhIQo4djLtRkceg-zaYjULYEjRoUToVEyOUVCFfZMUs_E7ZLSzjFmcg</reference>
  <id>45a27fd8d56c56dc62afc9b49e1d850440d5c403</id>
  <photo>
   <photo_reference>CnRnAAAAUW97jpK2_C2Lh4jLPVKZlhyS84mqZxvVmWFdc6jdl3XxjzKbYdbJpz0PGW5eFRw6kTKYNZM9QvRf-csFegHILZxLCLJ-6ZnbdEXbVM4kBzOb-rhchJx1KC6LHs_vVWP8bK96569lFYRf7Hn8ylQrlhIQb69_dcZVwqQhREsHW6azWhoU0XMWqZMBBzx-hgpduAaeErOFg8E</photo_reference>
   <width>640</width>
   <height>426</height>
  </photo>
 </result>
 <result>
  <name>Bucks Party Cruise</name>
  <vicinity>37 Bank St, Pyrmont</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8709430</lat>
    <lng>151.1903110</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJLfySpTOuEmsRsc_JfJtljdc</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBdAAAAOMUoYamsekTDxBDVyKZ-E54VQ6HjirVzAZBBwz5gcn5KTfmemmwmOAtLcvRScp1NLQmj-fBYzEO2Gq_cO4Dc12PG0_twzDv9zq3KIyNQVuO-r0n1eQVj8Dlng-n4c1F2hMxufCNVp4-QfjMj81qXJm0invQMUc1xNgZRyiOpLe9EhDLn0KiVWEFKOURYsWrHRouGhR7YMJxYmFs-OXjKyzQKGdQXLrzPw</reference>
  <id>30bee58f819b6c47bd24151802f25ecf11df8943</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAjboYP9Ujxe5SmZFN5AJc42AWtpYFX9wYdqjcTXavXJlfoXdHPC2hErdbHcaeYJBNPV6CzoDc2RLw_w9HofGOhCWHtoAl9b3g8TZZjnZobnAHxoljUdgV8PXyd-pCO-QHKOtiKfIdUmF4HRj2QHj6OhIQhLNpoKNKP8MNjk90M4KGrhoUW2NyBgsWjRpUEoWlt0fD48BhEcQ</photo_reference>
   <width>800</width>
   <height>600</height>
  </photo>
 </result>
 <result>
  <name>Australian Cruise Group</name>
  <vicinity>32 The Promenade, King Street Wharf 5, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675910</lat>
    <lng>151.2011960</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJrTLr-GyuEmsRBfy61i59si0</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBeAAAAJZA0WY2pKnZ6nNnxNd_pSDA2NilDLfGDf7pTt7VssxB5tMYE7400w3HZHRav2unpKRhEp7lrh0yKcVdSfKYIz85k1SExoLGmYD8NIf1dPr8KlkRWOYZUTLGp623r5hAzEGk94mPleF4s50pWqLrhAzwvJb1tGj2ak-2PXQORkeTEhAfTj6tMFo_tRWZYOnYCxiVGhQA3n-KV7AW5MvJlGaIDHuLyyEBBA</reference>
  <id>a97f9fb468bcd26b68a23072a55af82d4b325e0d</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAhTkpwozMoZx_NXMkIrKdcEGe46BmPy3GPCfS-gkCK5PlR8rFDY9DtD_7wFYAIdhVoZz3I9QguRNbil5y37jTU-03GJ_LqVw_avSxFkT0g2kU0K5z2VYnAsgNsrbsK_EVglhg5PrDybC1tAVKCXSGsRIQOcdlAVnC1Qc46YLWjlqdyxoUL5JGZgczfo1jxLxhDeGs8OvBQCk</photo_reference>
   <width>200</width>
   <height>242</height>
  </photo>
 </result>
</PlaceSearchResponse>

XML 回應是由單一 <PlaceSearchResponse> 和最多四個頂層元素所組成:

  • <status> 包含與要求相關的中繼資料。請參閱下方的狀態碼
  • 零個或多個 <result> 元素,每個元素皆包含單一機構的相關資訊。請參閱附近地點搜尋結果,以取得這些結果的相關資訊。Places API 針對每一查詢最多會傳回 20 個 establishment 結果。此外,還可能傳回 political <type> 結果或街道,這可用來識別要求的區域。
  • next_page_token 包含可用來傳回最多 20 個額外結果的語彙基元。如果沒有任何額外的結果可供顯示,將不會傳回 next_page_token。可傳回的結果數目上限為 60。next_page_token 會在初次發出的 2 秒後生效。
  • html_attributions 包含必須對使用者顯示、關於此清單的一組相關資料引用標示。

狀態碼

搜尋回應物件內的 "status" 欄位包含要求的狀態,並且可能包含可協助您探究要求失敗原因的偵錯資訊。"status" 欄位可能包含下列值:

  • OK 指出未發生任何錯誤;已順利偵測到地點並至少傳回一個結果。
  • ZERO_RESULTS 指出搜尋成功,但是未傳回任何結果。如果傳遞了遠端位置中的 latlng 給搜尋,就可能發生這種情況。
  • OVER_QUERY_LIMIT 指出已超出您的配額。
  • REQUEST_DENIED 指出您的要求已被拒絕,通常是因為缺少無效的 key 參數。
  • INVALID_REQUEST 通常指出缺少必要的查詢參數(locationradius)。

錯誤訊息

當「Google 地方資訊」服務傳回 OK 以外的狀態碼時,搜尋回應物件內可能會有額外的 error_message 欄位。此欄位包含有關所提供之狀態碼背後原因的更多詳細資訊。

搜尋結果

當「Google 地方資訊」服務從搜尋傳回 JSON 結果時,會將這些結果放在 results 陣列內。即使此服務未傳回任何結果(例如,如果 location 在遠端),仍會傳回空的 results 陣列。XML 回應是由零個或多個 <result> 元素所組成。

results 陣列的每個元素皆包含一個來自指定區域(locationradius)的結果,其排列順序是依據知名度。

此結果也可能包含必須對使用者顯示的資料引用標示資訊。以下是 JSON 格式的資料引用標示範例:

"html_attributions" : [
      "Listings by \u003ca href=\"http://www.example.com/\"\u003eExample Company\u003c/a\u003e"
],
以下是 XML 格式的資料引用標示範例:
<html_attribution>Listings by <a href="http://www.example.com/">Example Company</a></html_attribution>

results 陣列內的每個結果可能包含下列欄位:

  • icon 包含建議之圖示的 URL,此圖示是指示這個結果時,可能會對使用者顯示的圖示。
  • id 包含代表此地點的唯一固定識別碼。此識別碼無法用來擷取此地點的相關資訊,但是保證在所有工作階段都有效。它可用來合併此地點的相關資料,以及在各個個別的搜尋中驗證地點的身分。注意:id 現在已被 place_id 取代。請參閱此頁面上的過時通知
  • geometry 包含結果的相關幾何資訊,通常包括地點的 location(地理編碼)和(選擇性)識別其一般涵蓋範圍的 viewport
  • name 包含人類看得懂的傳回結果名稱。對於 establishment 結果,這通常是商家名稱。
  • opening_hours 可包含下列資訊:
    • open_now 是一個布林值,指出地點目前是否營業中。
  • photos[]photo 物件的陣列,每個物件皆包含影像的參照。「地點搜尋」將最多傳回一個 photo 物件。在地點執行「地點詳細資料」要求最多會傳回十張相片。如需有關「地點相片」及如何在您應用程式中使用影像的詳細資訊,請參閱地點相片文件。photo 物件以下列方式描述:
    • photo_reference - 當您執行「相片」要求時,用來識別相片的字串。
    • height - 影像的高度上限。
    • width - 影像的寬度上限。
    • html_attributions[] - 包含任何必要的資料引用標示。此欄位一律會存在,但可以為空白。
  • place_id — 可唯一識別地點的文字型識別碼。如果要擷取地點的相關資訊,請在 Places API 要求的 placeId 欄位中傳遞此識別碼。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • scope - 指出 place_id 的範圍。可能的值包括:
    • APP:此地點 ID 僅供您的應用程式識別。這是因為您的應用程式新增了該地點,而該地點尚未通過仲裁程序。
    • GOOGLE:此地點 ID 可供其他應用程式使用,以及在「Google 地圖」上使用。
    注意:scope 欄位只包括在「附近地點搜尋」結果和「地點詳細資料」結果中。您只能透過「附近地點搜尋」和「地點詳細資料」要求來擷取應用程式範圍的地點。如果回應中沒有 scope 欄位,則可以放心地假設範圍是 GOOGLE
  • alt_ids - 地點之內含零個、一個或多個替代地點 ID 的陣列,含有與每個替代 ID 相關的範圍。注意:此陣列可能是空的或不存在。如果存在,則會包含下列欄位:
    • place_id - 一個地點擁有替代地點 ID 的最可能原因,就是您的應用程式新增一個地點並收到應用程式範圍的地點 ID,然後稍後再於通過仲裁程序之後收到 Google 範圍的地點 ID。
    • scope - 替代地點 ID 的範圍將一律是 APP,表示此替代地點 ID 僅供您的應用程式識別。
    例如,假設您的應用程式新增一個地點,並收到新地點的 place_id AAA。稍後,此地點通過仲裁程序而收到 Google 範圍的 place_id BBB。從此以後,此地點的資訊將會包含:
        "results" : [
          {
            "place_id" : "BBB",
            "scope" : "GOOGLE",
            "alt_ids" : [
              {
                "place_id" : "AAA",
                "scope" : "APP",
              }
            ],
          }
        ]
        
  • price_level - 此地點的價格等級,等級為 0 到 4。特定值所代表的確切金額將因地區而異。價格等級的解釋如下:
    • 0 - 免費
    • 1 - 便宜
    • 2 - 適中
    • 3 - 昂貴
    • 4 - 非常昂貴
  • rating 包含地點的評分,從 1.0 到 5.0,以加總的使用者評論為依據。
  • reference 包含一個唯一語彙基元,可供您在地點詳細資料要求中擷取此地點的額外相關資訊。雖然此語彙基元可唯一識別此地點,但此地點並不僅限擁有一個語彙基元。一個地點可以有許多有效的參照語彙基元。無法保證針對任何指定的地點,在不同的搜尋中皆傳回相同的語彙基元。注意:reference 現在已被 place_id 取代。請參閱此頁面上的過時通知
  • types[] 包含描述所提供之結果的功能類型陣列。請參閱支援的類型清單以瞭解詳細資訊。如果指派多個類型給結果,XML 回應就會包括多個 <type> 元素。
  • vicinity 包含鄰近位置的功能名稱。通常此功能會參照所提供之結果內的街道或鄰近地區。vicinity 屬性是只有針對附近地點搜尋才會傳回的屬性。
  • formatted_address 是一個字串,包含人類看得懂的此地點地址。此地址通常等於「郵政地址」。formatted_address 屬性是只有針對文字搜尋才會傳回的屬性。
  • permanently_closed 是布林旗標,用來指出地點是否永久關閉(值為 true)。如果地點不是永久關閉,則回應中不會有該旗標存在。

加值資料

除了上面所列的欄位之外,擁有 Premium Plan 授權的 Google Places API 客戶還可能收到下列欄位。這些欄位將顯示為 result 欄位的頂層子項。

  • aspects 包含單一的 AspectRating 物件,用來做為該機構的「主要」評分。每個 AspectRating 皆以下列方式描述:
    • type - 所評分之觀點的名稱。支援下列類型:appealatmospheredecorfacilitiesfoodoverallqualityservice
    • rating - 此特定觀點的彙總評分,從 0 到 30。請注意,彙總評分的範圍是從 0 到 30,而在評論內的評分範圍是從 0 到 3。
  • zagat_selected 指出地點已被評選為 Zagat 優良地點。Zagat 標籤識別因其一貫高品質而著稱,或具有特殊或獨特特色的地點。
如需詳細資訊,請參閱加值資料

存取其他結果

根據預設,「附近地點搜尋」或「文字搜尋」針對每一查詢最多會傳回 20 個 establishment 結果;然而,每個搜尋可傳回多達 60 個紀錄,分列於三頁。如果您的搜尋會傳回超過 20 個結果,則搜尋回應將會包括一個額外的值,也就是 next_page_token 。將 next_page_token 的值傳遞給新搜尋的 pagetoken 參數,即可查看下一組結果。如果 next_page_token 為 Null 或未傳回,則不會有進一步的結果。在發出 next_page_token 到它變成有效之間,會有短暫延遲。在可取得下一頁之前就對其發出要求,將會傳回 INVALID_REQUEST 回應。以相同的 next_page_token 重試要求,將會傳回下一頁結果。

例如,在以下查詢中,我們將搜尋澳洲雪梨達令港附近的餐廳,並依據距離排列結果。您會看到回應包含 next_page_token 屬性。

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&rankby=distance&types=food&key=YOUR_API_KEY
{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867217,
               "lng" : 151.195939
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png",
         "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7",
         "name" : "Biaggio Cafe - Pyrmont",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAmWmj0BqA0Jorm1_vjAvx1n6c7ZNBxyY-U9x99-oNyOxvMjDlo2npJzyIq7c3EK1YyoNXdMFDcRPzwLJtBzXAwCUFDGo_RtLRGBPJTA2CoerPdC5yvT2SjfDwH4bFf5MrznB0_YWa4Y2Qo7ABtAxgeBIQv46sGBwVNJQDI36Wd3PFYBoUTlVXa0wn-zRITjGp0zLEBh8oIBE",
               "width" : 900
            }
         ],
         "place_id" : "ChIJIfBAsjeuEmsRdgu9Pl1Ps48",
         "scope" : "GOOGLE",
         "price_level" : 1,
         "rating" : 3.4,
         "reference" : "CoQBeAAAAGu0wNJjuZ40DMrRe3mpn7fhlfIK1mf_ce5hgkhfM79u-lqy0G2mnmcueTq2JGWu9wsgS1ctZDHTY_pcqFFJyQNV2P-kdhoRIeYRHeDfbWtIwr3RgFf2zzFBXHgNjSq-PSzX_OU6OT2_3dzdhhpV-bPezomtrarW4DsGl9uh773yEhDJT6R3V8Fyvl_xeE761DTCGhT1jJ3floFI5_c-bHgGLVwH1g-cbQ",
         "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866786,
               "lng" : 151.195633
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
         "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 1260,
               "html_attributions" : [ "From a Google User" ],
               "photo_reference" : "CnRwAAAAeM-aLqAm573T44qnNe8bGMkr_BOh1MOVQaA9CCggqtTwuGD1rjsviMyueX_G4-mabgH41Vpr8L27sh-VfZZ8TNCI4FyBiGk0P4fPxjb5Z1LrBZScYzM1glRxR-YjeHd2PWVEqB9cKZB349QqQveJLRIQYKq2PNlOM0toJocR5b_oYRoUYIipdBjMfdUyJN4MZUmhCsTMQwg",
               "width" : 1890
            }
         ],
         "place_id" : "ChIJ5xQ7szeuEmsRs6Kj7YFZE9k",
         "scope" : "GOOGLE",
         "reference" : "CnRvAAAA22k1PAGyDxAgHZk6ErHh_h_mLUK_8XNFLvixPJHXRbCzg-gw1ZxdqUwA_8EseDuEZKolBs82orIQH4m6-afDZV9VcpggokHD9x7HdMi9TnJDmGb9Bdh8f-Od4DK0fASNBL7Me3CsAWkUMWhlNQNYExIQ05W7VbxDTQe2Kh9TiL840hoUZfiO0q2HgDHSUyRdvTQx5Rs2SBU",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "aspects" : [
            {
               "rating" : 23,
               "type" : "overall"
            }
         ],
      ...
   ],
   "status" : "OK"
}

如果要查看下一組結果,您可以提交新的查詢,將 next_page_token 的結果傳遞給 pagetoken 參數。例如:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY

設定 pagetoken 將會導致忽略任何其他參數。此查詢將執行與以前一樣的搜尋,但是會傳回一組新的結果。在原始查詢之後,您最多可以發出兩次新頁面要求。每一頁結果必須依序顯示。單一查詢不應顯示兩頁或更多頁查詢結果做為其結果。請注意,每個搜尋都會被視為一個要求,並計入您的使用限制。

sensor 參數

Google Places API 先前要求您包括 sensor 參數,以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。

傳送您對下列選項的寶貴意見...

這個網頁
location_on
Google Places API Web Service