地點 ID

選取平台： Android iOS JavaScript 網路服務

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

  • 在 Geocoding API Web 服務和 Maps JavaScript API 地理編碼服務中，擷取地點 ID 代表的地址。
  • 在 Routes API 和 Directions API Web 服務和 Maps JavaScript API 路線規劃服務中，指定起點、目的地和中繼路線控點。
  • 在 Routes API 和 Distance Matrix API Web 服務和 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 SDK for iOS 使用範例

地點 ID 是用來識別特定地點的文字 ID，在 Places SDK for iOS 中，您可以從 GMSPlace 物件擷取地點 ID。您可以儲存地點 ID，日後再次用於擷取 GMSPlace 物件。

如要透過 ID 取得地點，請呼叫 GMSPlacesClient fetchPlaceFromPlaceID: 並傳遞下列參數：

  • 包含地點 ID 的字串。
  • 一或多個 GMSPlaceField，用於指定要傳回的資料類型。
  • 如果呼叫是為了結束自動完成查詢而發出的工作階段符記，否則請傳遞 nil。
  • 用於處理結果的 GMSPlaceResultCallback。

API 會叫用指定的回呼方法，並傳入 GMSPlace 物件。如果找不到地點，則地點物件為 nil。

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

儲存地點 ID 供日後使用

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

重新整理已儲存的地點 ID

如果地點 ID 儲存超過 12 個月，建議您重新整理。您可以免付費重新整理地點 ID，方法是提出 Place Details 要求，且只指定 fields 參數中的 GMSPlaceFieldPlaceID 欄位。這項呼叫會觸發 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