您已全部設定完成!

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

啟用 Google Places API Web Service

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

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

地點自動完成

「地點自動完成」服務是一個 Web 服務,可在對 HTTP 要求的回應中傳回地點預測。此要求會指定一個文字型搜尋字串和選擇性的地理邊界。此服務可針對文字型地理搜尋提供自動完成功能,方法是在使用者輸入的同時傳回商家、地址和搜尋點等地方資訊。

地點自動完成要求

「地點自動完成」服務是 Google Places API Web Service 的一部分,與 Google Places API Web Service 共用 API 金鑰和配額。

「地點自動完成」服務可以比對完整單字,也可以比對子字串。因此,應用程式可在使用者輸入的同時傳送查詢,以提供隨打即找的地點預測。

傳回的預測是設計來呈現給使用者,以協助他們選取想要的地點。您可以傳送地點詳細資料要求,以取得所傳回之任何地點的相關詳細資訊。

「地點自動完成」要求是具有下列格式的 HTTP URL:

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

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

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

某些參數是起始「地點自動完成」要求的必要參數。根據 URL 標準,所有參數都使用 & 字元來分隔。參數清單與其可能值列舉如下。

必要參數

  • input - 做為搜尋依據的文字字串。「地點自動完成」服務將會依據此字串傳回相符的候選項目,並依據所感知的結果相關性排列結果順序。
  • key - 您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。如需詳細資訊,請參閱取得金鑰Google Maps API 進階方案 客戶必須使用購買 Premium Plan 過程中為他們建立的 API 專案。

選擇性參數

  • offset - 服務用來比對預測的最後一個字元在輸入字詞中的位置。例如,如果輸入是 'Google' 而 offset 是 3,服務將會依據 'Goo' 進行比對。offset 所決定的字串只會與輸入字詞中的第一個單字比對。例如,如果輸入字詞是 'Google abc' 而 offset 是 3,服務將會嘗試與 'Goo abc' 比對。如果未提供任何 offset,服務將會使用整個字詞。offset 通常應該設定為文字插入號的位置。
  • location - 您想要擷取其周圍地點資訊的點。必須以「緯度,經度」的方式指定。
  • radius - 要傳回地點結果的距離範圍 (單位為公尺)。請注意,設定 radius 會將結果偏向指示的區域,但可能不會將結果完全限制在指定的區域。請參閱下方的位置偏向位置限制
  • language - 語言代碼,指出應該以哪一種語言傳回結果 (如果可能的話)。搜尋也會偏向所選的語言;使得所選語言會獲得較高的排名。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。如果未提供語言,「地點自動完成」服務將會嘗試使用傳送要求時來源地區的當地語言。
  • types - 要傳回之地點結果的類型。請參閱下方的地點類型。如果未指定任何類型,將會傳回所有類型。
  • components - 一組您想要用來限制結果的地點。目前,您可以使用 components 來依國家/地區進行篩選。傳遞國家/地區時,必須使用與 ISO 3166-1 Alpha-2 相容的兩字元國家/地區代碼。例如:components=country:fr 會將您的結果限制在法國境內的地點。
  • strictbounds — 僅傳回確實位於 locationradius 所定義區域內的那些地點。這是一個限制,而不是偏向,也就是說,不在此區域內的結果都不會傳回,即使是符合使用者輸入也一樣。

位置偏向

您可以透過傳遞 locationradius 參數,將結果偏向指定的圓形範圍。這會將「地點自動完成」服務引導成「偏好」顯示該範圍內的結果。該定義區域外的結果仍然會顯示。您可以使用 components 參數來篩選結果,只顯示指定之國家/地區內的地點。

祕訣:當搜尋區域很大時,機構結果通常會因為排名不夠高而無法出現在結果中。如果您想要讓機構出現在機構/地理編碼的混合結果中,您可以指定一個較小的半徑。或者,也可以使用 types=establishment,將結果限制為只有機構。

位置限制

您也可以藉著新增 strictbounds 參數,將結果限制在 locationradius 定義的區域。這會將「地點自動完成」服務引導成「只」傳回該區域內的結果。

地點類型

透過傳遞 types 參數,您可以將來自「地點自動完成」要求的結果限制為特定類型。此參數可指定類型或類型集合,如下列支援的類型。如果未指定任何類型,則會傳回所有類型。通常只允許單一類型。geocodeestablishment 類型算是例外,您可以放心地混用兩者,但請注意,這與不指定任何類型的效果相同。支援的類型包括:

  • geocode 會指示「地點自動完成」服務只傳回地理編碼結果,而不傳回商家結果。一般而言,當所指定的位置可能不明確時,您可以使用此要求讓結果更加明確。
  • address 會指示「地點自動完成」服務只傳回具有精確地址的地理編碼結果。一般而言,當您知道使用者將尋找完整指定的地址時,便可以使用此要求。
  • establishment 會指示「地點自動完成」服務只傳回商家結果。
  • (regions) 類型集合會指示「地方資訊」服務傳回任何與下列類型相符的結果:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • (cities) 類型集合會指示「地方資訊」服務傳回與 localityadministrative_area_level_3 相符的結果。

範例自動完成要求

針對位於以加州舊金山為中心之區域內並包含 "Amoeba" 字串之機構的要求:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

相同要求,不過限制在距離舊金山 Ashbury 街與 Haight 街 500 公尺內的結果:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

針對包含 "Vict" 且有法文結果之地址的要求:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

針對包含 "Vict" 且有巴西葡萄牙文結果之城市的要求:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

請注意,您將必須以您自己的金鑰取代這些範例中的 API 金鑰

地點自動完成回應

傳回「地點自動完成」回應時,會依照要求之 URL 路徑內 output 旗標所指示的格式傳回。下方的結果指出針對具有下列參數的查詢可能傳回什麼資訊:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

JSON 回應包含兩個根元素:

  • status 包含與要求相關的中繼資料。請參閱下方的狀態碼
  • predictions 包含地點陣列與地點的相關資訊。請參閱地點自動完成結果,以取得這些結果的相關資訊。Google Places API Web Service 最多會傳回 5 個結果。

結果中特別值得注意的是 place_id 元素,此元素可用來透過個別查詢,要求關於地點的更特定詳細資料。請參閱地點詳細資料要求

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

XML 回應是由單一 <AutocompletionResponse> 元素搭配兩種類型的子元素所組成:

  • 單一 <status> 元素包含與要求相關的中繼資料。請參閱下方的狀態碼
  • 零個或多個 <prediction> 元素,每個元素皆包含單一地點的相關資訊。請參閱地點自動完成結果,以取得這些結果的相關資訊。Google Places API Web Service 最多會傳回 5 個結果。

除非您的應用程式因某種理由而要求使用 xml,否則建議您使用 json 做為慣用的輸出旗標。處理 XML 樹狀結構時必須謹慎小心,如此您才能參照正確的節點和元素。請參閱使用 XPath 剖析 XML,以取得處理 XML 的說明。

狀態碼

「地點自動完成」回應物件內的 status 欄位包含要求的狀態,並且可能包含可協助您探究「地點自動完成」要求失敗原因的偵錯資訊。status 欄位可能包含下列值:

  • OK 指出未發生任何錯誤,並且已至少傳回一個結果。
  • ZERO_RESULTS 指出搜尋成功,但是未傳回任何結果。如果傳遞了遠端位置中的 bounds 給搜尋,就可能發生這種情況。
  • OVER_QUERY_LIMIT 指出已超出您的配額。
  • REQUEST_DENIED 指出您的要求已被拒絕,通常是因為缺少無效的 key 參數。
  • INVALID_REQUEST 通常指出缺少 input 參數。

錯誤訊息

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

地點自動完成結果

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

每個預測結果皆包含下列欄位:

  • description 包含人類看得懂的傳回結果名稱。對於 establishment 結果,這通常是商家名稱。
  • place_id 是可唯一識別地點的文字型識別碼。如果要擷取地點的相關資訊,請在 Google Places API Web Service 要求的 placeId 欄位中傳遞此識別碼。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • reference 包含一個唯一語彙基元,可供您在地點詳細資料要求中擷取此地點的額外相關資訊。雖然此語彙基元可唯一識別此地點,但此地點並不僅限擁有一個語彙基元。一個地點可以有許多有效的參照語彙基元。無法保證針對任何指定的地點,在不同的搜尋中皆傳回相同的語彙基元。注意:reference 已被 place_id 取代。請參閱此頁面上的過時通知
  • id 包含代表此地點的唯一固定識別碼。此識別碼無法用來擷取此地點的相關資訊,但可用來合併此地點的相關資料,以及在個別的搜尋中驗證地點的識別資訊。注意:id 已被 place_id 取代。請參閱此頁面上的過時通知
  • terms 包含字詞陣列,這些字詞識別所傳回之描述的每個區段 (描述區段通常是以逗號做為結尾)。陣列中的每個項目都有一個 value 欄位,當中包含此字詞的文字;還有一個 offset 欄位,用來定義此字詞在描述中的起始位置 (單位為 Unicode 字元)。
  • types 包含適用此地點的類型陣列。例如:[ "political", "locality" ][ "establishment", "geocode" ]
  • matched_substrings 包含附有 offset 值和 length 的陣列。這些可描述所輸入之字詞在預測結果文字中的位置,以便視需要將此字詞醒目標示。

sensor 參數

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

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

這個網頁
location_on
Google Places API Web Service