地點 ID

選取平台： Android iOS JavaScript Web 服務

地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。系統會在傳送至下列 Maps API 的要求中，接受地點 ID：

  • 在 Geocoding API Web 服務和 Maps JavaScript API 地理編碼服務中，擷取地點 ID 代表的地址。
  • 在 Routes API 和 Directions API (舊版) 網路服務和 Maps JavaScript API (舊版) 路線規劃服務中，指定起點、目的地和中繼路線控點。
  • 在 Routes API 和 Distance Matrix API (舊版) 網路服務和 Maps JavaScript API 距離矩陣服務 (舊版) 中，指定起點和目的地。
  • 在 Places API Web 服務、Places SDK for Android、Places SDK for iOS 和 Places Library 中，擷取 Place Details。
  • 在 Maps Embed API 中使用地點 ID 參數。
  • 在 Google 地圖網址中擷取搜尋查詢。
  • 在 Roads API 中顯示速限。
  • 在界線資料導向樣式中，搜尋界線多邊形及設定樣式。

找出特定地點的 ID

如要查看特定地點的 ID，請使用下方的地點 ID 搜尋器，搜尋地點並取得 ID：

或者，您也可以在 Maps JavaScript API 說明文件中，查看地點 ID 搜尋器及相關程式碼。

總覽

地點 ID 是用來識別特定地點的文字 ID，長度不一 (地點 ID 沒有長度上限)。範例：

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

大多數地點 (包括商家、地標、公園和十字路口) 都有地點 ID，同一個地點或位置可能會有多個不同的地點 ID。此外，地點 ID 也可能會隨著時間改變。

您可以在 Places API 和多個 Google 地圖平台 API，使用同一個地點 ID。舉例來說，您可以使用同一個地點 ID 來參照 Places API、Maps JavaScript API、Geocoding API、Maps Embed API 和 Roads API 中的一個地點。

使用地點 ID 擷取地點詳細資料

地點 ID 的常見用途是搜尋地點 (例如使用 Places API 或 Maps JavaScript API Places Library)，然後使用傳回的地點 ID 擷取地點詳細資料。您可以儲存地點 ID，日後用於擷取相同的地點詳細資料。請參閱下方的儲存地點 ID 相關資訊。

以下範例說明如何為 Places API (新版) 和 Places API 要求圖示網址。

Places API (新推出)

您可以使用 Places API 發出 Text Search (新版) 要求，找出地點 ID。

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

回應會在 id 欄位中包含地點 ID，如下所示：

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

您現在可以透過在要求網址中加入地點 ID，提出 Places API (新版) 要求：

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API

您可以使用 Places API 發出 Place Search 要求，找出地點 ID。

以下範例是搜尋要求，要求系統在澳洲雪梨的某個地點 1,500 公尺範圍內，找出含有「遊輪」一詞的餐廳類型地點：

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

回應會在 place_id 欄位中加入地點 ID，如以下程式碼片段所示：

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

您現在可以傳送 Place Details 要求，並將地點 ID 放入 place_id 參數：

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

儲存地點 ID 供日後使用

地點 ID 不受《Google 地圖平台服務條款》第 3.2.3(b) 節的快取限制約束。因此，您可以儲存地點 ID 值供日後使用。

重新整理已儲存的地點 ID

如果地點 ID 儲存超過 12 個月，Google 建議您重新整理。您可以免付費重新整理地點 ID，方法是提出 Place Details 要求，且只指定 fields 參數中的地點 ID 欄位。

Places API (新推出)

例如，使用 Places API (新版)：

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API

例如，使用舊版 Places API API：

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

這項呼叫會觸發 Place Detail New Essentials IDs Only 或 Places Details - ID Refresh SKU。

這項要求也可能會傳回 NOT_FOUND 狀態碼。其中一種策略是儲存傳回每個地點 ID 的原始要求。如果地點 ID 失效，您可以重新提出要求，取得最新結果，這些結果不一定會包含原始地點。不過，這項要求會產生費用。

使用地點 ID 時的錯誤代碼

INVALID_REQUEST 狀態碼表示指定的地點 ID 無效。如果地點 ID 遭到截斷、或經過修改導致該值不再正確，系統可能會傳回 INVALID_REQUEST。

NOT_FOUND 狀態碼表示指定的地點 ID 已過時。如果商家已停業或搬遷至新地點，地點 ID 可能就會過時。Google 地圖資料庫更新時，地點 ID 可能會有變動。在這種情況下，地點可能會獲得新 ID，而舊 ID 會傳回 NOT_FOUND 回應。

特別是，部分類型的地點 ID 有時可能會產生 NOT_FOUND 回應，或者 API 可能會在回應中傳回其他地點 ID。這些地點 ID 類型包括：

  • 街道地址，這類地址在 Google 地圖中並非精確地址，是系統根據一系列地址推斷而得。
  • 長路線路段，要求並且指定了縣市。
  • 十字路口。
  • 地址元件類型為 subpremise 的地點。

這類 ID 通常採用長字串的形式 (地點 ID 沒有長度上限)。舉例來說：

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4