地點 ID

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

地點 ID 可明確識別 Google 地方資訊資料庫和 Google 地圖上的地點。下列 Maps API 的要求接受地點 ID:

  • 擷取 Geocoding API 網路服務和 Geocoding Service (Maps JavaScript API) 中地點 ID 的地址。
  • 在 Directions API 網路服務和 Directions Service (Maps JavaScript API) 中指定起點、目的地和中繼路線控點。
  • 在 Distance Matrix API 網路服務和距離 JavaScript 服務 (Maps JavaScript API) 中指定起點和目的地。
  • 擷取 Places API 網路服務、Places SDK for Android、Places SDK for iOS 和 Places Library、JavaScript API 中的 Place Details。
  • 在 Maps Embed API 中使用地點 ID 參數。
  • 在 Google 地圖網址中擷取搜尋查詢。
  • 在 Roads API 中顯示速限。
  • 搜尋及設定以數據為準的樣式邊界多邊形樣式。

找出特定地點的 ID

你是否正在尋找特定地點的地點 ID?使用下方的地點 ID 搜尋器搜尋地點並取得 ID:

或者,您也可以使用 Maps JavaScript API 說明文件中的查看地點 ID 搜尋器

總覽

地點 ID 是用來識別地點的文字 ID。ID 的長度可能不同 (地點 ID 沒有上限)。範例:

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

大多數地點 (包括商家、地標、公園和十字路口) 都能使用地點 ID,同一個地點或地點可能會有多個不同的地點 ID。搜尋 ID 可能會隨著時間改變。

您可在 Places API 和多個 Google 地圖平台 API 中使用相同的地點 ID。舉例來說,您可以使用同一個地點 ID 來參照 Places APIMaps JavaScript APIGeocoding APIMaps Embed APIRoads API 中的地點。

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

地點 ID 不受《Google 地圖平台服務條款》第 3.2.3(b) 節中規定的快取限制影響。找到地點 ID 後,你就能在下次查詢該地點時重複使用該值。詳情請參閱下方的儲存地點 ID 供日後使用一節。

使用地點 ID 的常見方法是搜尋地點 (例如使用 Maps JavaScript API 的 Places APIPlaces 程式庫),然後使用傳回的地點 ID 擷取地點詳細資料。您可以儲存地點 ID,用來日後擷取相同的地點詳細資料。詳情請參閱下方的儲存地點 ID 一節。

使用 Places API 的範例

使用 Places API 時,您可以透過 Place Search 要求尋找地點 ID。

以下舉例說明搜尋在澳洲雪梨某地點半徑 1500 公尺內,且包含「##39;cruise'」這個字詞的搜尋要求 '餐廳'

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 要求,在 place_id 參數中加入地點 ID:

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

儲存地點 ID 以供日後使用

地點 ID 不必符合《Google 地圖平台服務條款》第 3.2.3(a) 節所述的快取限制。您可以儲存地點 ID 值以供日後使用。

正在重新整理已儲存的地點 ID

如果地點 ID 超過 12 個月,建議您重新整理 ID。如有需要,您可以呼叫 Place Details 要求,並在 fields 參數中指定 place_id 欄位,藉此重新整理地點 ID。這會觸發 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