地點 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 中,您可以透過下列方式擷取地點 ID:
撥號中
Place.getId()
。
Place Autocomplete 服務
也會傳回與所提供搜尋查詢相符的每個地點的地點 ID
和篩選器使用地點 ID 擷取
Place
敬上
物件。
如要依 ID 取得地點,請呼叫
PlacesClient.fetchPlace()
、
傳遞 FetchPlaceRequest
。
API 會傳回
FetchPlaceResponse
敬上
風格
Task
。
FetchPlaceResponse
敬上
包含
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