地點 ID

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

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

  • 在 Geocoding API 網路服務和 Maps JavaScript API 地理編碼服務中,擷取地點 ID 所代表的地址。
  • 在 Directions API 網路服務和 Maps JavaScript API 路線規劃服務中,指定起點、目的地和中繼路線控點。
  • 在 Distance Matrix API 網路服務和 Maps JavaScript API 距離矩陣服務中,指定起點和目的地。
  • 在 Places API 網路服務、Places SDK for Android、Places SDK for iOS 和 JavaScript API 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 APIMaps JavaScript APIGeocoding APIMaps Embed APIRoads API 中的地點。

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

地點 ID 不受《Google 地圖平台服務條款》第 3.2.3(b) 節所述快取限制的約束。找到地點的 ID 後,您就可以在下次查詢該地點時重複使用這個值。詳情請參閱下方的「儲存地點 ID 供日後使用」一節。

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

Places SDK for Android 範例

在 Places SDK for Android 中,您可以呼叫 Place.getId() 來擷取地點 ID。Place Autocomplete 服務也會針對與提供的搜尋查詢和篩選器相符的每個地點,傳回地點 ID。稍後使用地點 ID 再次擷取 Place 物件。

如要依 ID 取得地點,請呼叫 PlacesClient.fetchPlace() 以傳遞 FetchPlaceRequest

API 會在 Task 中傳回 FetchPlaceResponseFetchPlaceResponse 包含與提供地點 ID 相符的 Place 物件。

以下程式碼範例顯示呼叫 fetchPlace() 以取得指定地點的詳細資料。

Java


// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Kotlin


// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

儲存地點 ID 供日後使用

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

重新整理已儲存的地點 ID

如果地點 ID 已產生超過 12 個月,建議您重新整理。您可以免付費重新整理地點 ID,方法是提出 Place Details 要求,且只指定 fields 參數中的 Place.Field.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