地點 ID

選取平台： Android iOS JavaScript Web 服務

地點 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 Android 的範例

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

如要透過 ID 取得地點，請呼叫 PlacesClient.fetchPlace()，並傳遞 FetchPlaceRequest。

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

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

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")
        }
    }

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.
    }
});

儲存地點 ID 供日後使用

地點 ID 不受《Google 地圖平台服務條款》第 3.2.3(b) 節的快取限制約束。因此，您可以儲存地點 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