您已全部設定完成!

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

啟用 Google Places API Web Service

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

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

地點新增

透過新增地點,您能以來自您應用程式的資料補充 Google 地圖資料庫中的資料。這樣可讓您:

  • 立即為您的使用者更新 Google 資料庫中的資料。
  • 提交新的地點到仲裁佇列,以便新增到 Google 地方資訊資料庫。
  • 使您的應用程式與其他功能相似的應用程式有所區別。
  • 建立以特定使用者群或地理位置為目標的應用程式。
  • 影響從您應用程式發出之「地方資訊搜尋」的結果。
  1. 總覽
  2. 新增地點
  3. 刪除地點
  4. 狀態碼
  5. 錯誤訊息
  6. sensor 參數

總覽

當您新增地點時,這個新的地點會立刻出現在您的應用程式所起始的「附近地點搜尋」。這個新的地點也會進入仲裁佇列,被考慮納入「Google 地圖」中。新增的地點在獲得仲裁程序核准之前,不會出現在「文字搜尋」或「雷達搜尋」結果中,也不會對其他應用程式顯示。

由您應用程式新增的地點只要尚未通過仲裁,您也可以將它刪除。地點一旦通過仲裁並新增到 Google 資料庫中,您便無法將它刪除。尚未獲得仲裁程序接受的地點將可繼續被提交它們的應用程式看見。

新增地點

地點新增要求是類似以下範例的 HTTP POST 要求:


JSON
POST https://maps.googleapis.com/maps/api/place/add/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "location": {
    "lat": -33.8669710,
    "lng": 151.1958750
  },
  "accuracy": 50,
  "name": "Google Shoes!",
  "phone_number": "(02) 9374 4000",
  "address": "48 Pirrama Road, Pyrmont, NSW 2009, Australia",
  "types": ["shoe_store"],
  "website": "http://www.google.com.au/",
  "language": "en-AU"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/add/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceAddRequest>
  <location>
    <lat>-33.8669710</lat>
    <lng>151.1958750</lng>
  </location>
  <accuracy>50</accuracy>
  <name>Google Shoes!</name>
  <phone_number>(02) 9374 4000</phone_number>
  <address>48 Pirrama Road, Pyrmont, NSW 2009, Australia</address>
  <type>shoe_store</type>
  <website>http://www.google.com.au/</website>
  <language>en-AU</language>
</PlaceAddRequest>
      

請注意,URL 路徑會指出輸入和輸出的格式:

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

URL 必須包含下列參數:

  • key - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓從您應用程式新增的地點能夠立即供您的應用程式使用。如需詳細資訊,請參閱取得金鑰

要求主體包含地點的相關資訊。其建構方式應該根據指定的 output 參數(JSON 或 XML)。

  • accuracy - 此要求所依據之位置信號的精確度,以公尺表示。
  • address (建議,用來提高通過仲裁的機率) - 您要新增之地點的地址。如果地點具有格式正確、人類看得懂的地址,就比較可能通過仲裁程序而被納入「Google 地圖」資料庫中。
  • language - 回報地點名稱時所使用的語言。請參閱支援的語言清單與其代碼。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。
  • location (必要) - 您要新增之地點的地理位置,以緯度與經度值指定。
  • name (必要) - 地點的完整文字名稱。上限為 255 個字元。
  • phone_number (建議,用來提高通過仲裁的機率) - 與地點關聯的電話號碼。如果地點具有格式正確的電話號碼,就比較可能通過仲裁程序而被納入「Google 地圖」資料庫中。此號碼應該使用當地或國際格式:
    • 當地格式可能因國家/地區而異。請參閱維基百科文章。例如,Google 的澳洲雪梨辦公室當地電話號碼是 (02) 9374 4000
    • 國際格式包括國碼,而且前面加上加號 (+)。例如,Google 的澳洲雪梨辦公室國際電話號碼是 +61 2 9374 4000
  • types (必要) - 此地點所屬的類別。雖然 types 接受陣列,但是目前只能為地點指定一個類型。XML 要求所需的是單一 <type> 元素。請參閱支援的類型清單以瞭解詳細資訊。如果支援的類型中沒有與此地點相符的類型,您可以指定 other
  • website (建議,用來提高通過仲裁的機率) - 指向此地點之權威網站 (例如店家首頁) 的 URL。如果地點具有格式正確的網站位址,就比較可能通過仲裁程序而被納入「Google 地圖」資料庫中。

地點新增回應

傳回地點新增回應時,會依照要求之 URL 路徑中 output 參數所指示的格式傳回。

API 會傳回狀態碼,而且如果要求成功,回應會包括下列新地點屬性:

  • place_id:可唯一識別地點的文字型識別碼。如果要擷取地點的相關資訊,請在「地點詳細資料」要求的 placeid 欄位中傳遞此識別碼。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • scope:指出 place_id 的範圍。此欄位的可能值包括:
    • APP:此地點 ID 僅供您的應用程式識別。注意:地點新增回應一律是以 APP 為範圍,因為地點尚未通過仲裁程序。
    • GOOGLE:此地點 ID 可供其他應用程式使用,以及在「Google 地圖」上使用。如上面所提到的,地點新增回應一律不會以整個 Google 為範圍。
  • reference:可供您用來擷取此地點之額外相關資訊的唯一語彙基元。注意:reference 已被 place_id 取代。請參閱此頁面上的過時通知
  • id:代表此地點的唯一固定識別碼。此識別碼無法用來擷取此地點的相關資訊,但是保證在所有工作階段都有效。它可用來合併此地點的相關資料,以及在各個個別的搜尋中驗證地點的身分。注意:id 已被 place_id 取代。請參閱此頁面上的過時通知
{
  "status": "OK",
  "place_id": "CdIJN2t_tDeuEmsRUsoyG83frY4",
  "scope": "APP",
  "reference": "CiQgAAAAeTQS1RtzAyVRVjHcRiIWmWeqcAl3k7bluW7GINLDULESEHozTQhy6OHJw03ziDvY1uEaFAP_vDRhK-UbWw3Gd7Ulqm3eRjIs",
  "id": "6947fc4007436a71dbda51ef9a58627c8e8858f9"
}

刪除地點

只有在下列情況下才能刪除地點:

  • 該地點當初是由要求刪除的應用程式所新增。
  • 地點新增要求尚未順利通過「Google 地圖」仲裁程序,因此只有新增它的應用程式才能看見它。

如果嘗試刪除不符合這些條件的地點,API 將會傳回 REQUEST_DENIED 狀態碼。

地點刪除要求為下列格式的 HTTP POST 要求:


JSON
POST https://maps.googleapis.com/maps/api/place/delete/json?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

{
  "place_id": "place ID"
}
      
XML
POST https://maps.googleapis.com/maps/api/place/delete/xml?key=YOUR_API_KEY HTTP/1.1
Host: maps.googleapis.com

<PlaceDeleteRequest>
  <place_id>place ID</place_id>
</PlaceDeleteRequest>
      

請注意,URL 路徑會指出輸入和輸出的格式:

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

URL 必須包含下列參數:

  • key - 您應用程式的 API 金鑰。此金鑰可識別您的應用程式來進行配額管理,並且讓從您應用程式新增的地點能夠立即供您的應用程式使用。如需詳細資訊,請參閱取得金鑰

要求主體的建構方式應該根據指定的 output 參數 (JSON 或 XML)。它必須包括下列兩個欄位之一:

  • place_id:一個識別必須刪除之地點的字串,由地點搜尋傳回。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
  • 或者,您可以指定 reference 來識別該地點。請注意,reference 已被 place_id 取代。請參閱此頁面上的過時通知

地點刪除回應

傳回地點刪除回應時,會依照要求之 URL 路徑中 output 參數所指示的格式傳回。

成功的刪除要求會傳回下列狀態碼:

{
  "status": "OK"
}

狀態碼

地點新增/刪除要求的狀態碼包括:

  • OK 指出未發生任何錯誤;已順利新增或刪除地點。
  • UNKNOWN_ERROR 指出發生伺服器端錯誤;再試一次可能就會成功。
  • OVER_QUERY_LIMIT 指出已超出您的配額。
  • REQUEST_DENIED 指出您的要求已被拒絕。這有可能是因為嘗試刪除的地點是另一個應用程式所新增,或已通過「Google 地圖」仲裁程序。
  • INVALID_REQUEST 通常指出要求缺少參數。嘗試新增 name 大於 255 個字元的地點時,也會傳回此代碼。
  • NOT_FOUND 是針對地點刪除要求傳回的代碼,指出所傳遞的參照無法解析成地點。

錯誤訊息

當 Google Places API Web Service 傳回 OK 以外的狀態碼時,回應物件內可能會有額外的 error_message 欄位。此欄位包含有關所提供之狀態碼背後原因的更多詳細資訊。

sensor 參數

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

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

這個網頁
location_on
Google Places API Web Service