使用 Places SDK for Android,您可以探索裝置目前回報位置的地點。地點的例子包括當地商家、景點和地理位置。
權限
如要使用這個程式庫,您不需要在應用程式的資訊清單中宣告任何額外權限,因為程式庫會在其資訊清單中宣告所用權限。不過,如果您的應用程式使用 PlacesClient.findCurrentPlace()
,則必須在執行階段要求位置存取權。
如果您的應用程式未使用 PlacesClient.findCurrentPlace()
,請在資訊清單中加入以下內容,明確移除程式庫引入的 ACCESS_FINE_LOCATION
和 ACCESS_COARSE_LOCATION
權限:
<manifest ... xmlns:tools="http://schemas.android.com/tools"> ... <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/> ... </manifest>
進一步瞭解 權限,並考慮使用 EasyPermissions 開始使用。
取得目前位置
如要找出裝置目前所在地的當地商家或其他地點,請按照下列步驟操作:
- 呼叫
ContextCompat.checkSelfPermission
,檢查使用者是否已授予存取裝置位置資訊的權限。您的應用程式也必須包含程式碼,以便向使用者要求權限,並處理結果。詳情請參閱「要求應用程式權限」。 - 建立
FindCurrentPlaceRequest
,傳遞Place.Field
的List
,指定應用程式應要求的地點資料類型。 - 呼叫
PlacesClient.findCurrentPlace()
,傳遞您在上一個步驟中建立的FindCurrentPlaceRequest
。 - 從
FindCurrentPlaceResponse
取得PlaceLikelihood
清單。
欄位會與 Place Search 結果相對應,並分為三種計費類別:「Basic」、「Contact」和「Atmosphere」。「Basic」欄位以基本費率計費,不會產生額外費用。「Contact」和「Atmosphere」欄位會以較高的費率計費。如要進一步瞭解地點資料要求的計費方式,請參閱「用量與計費」一文。
API 會在 Task
中傳回 FindCurrentPlaceResponse
。FindCurrentPlaceResponse
包含 PlaceLikelihood
物件清單,代表裝置可能所在的地點。每個地點的結果都會顯示該地點是否為正確地點的可能性。如果沒有與指定裝置位置相對應的已知地點,清單可能會是空白。
您可以呼叫 PlaceLikelihood.getPlace()
來擷取 Place
物件,並呼叫 PlaceLikelihood.getLikelihood()
取得地點的可能性評分。值越高,代表該地點與搜尋字詞相符的可能性越高。
下列程式碼範例會擷取裝置最有可能所在的地點清單,並記錄每個地點的名稱和可能性。
Kotlin
// Use fields to define the data types to return. val placeFields: List<Place.Field> = listOf(Place.Field.NAME) // Use the builder to create a FindCurrentPlaceRequest. val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields) // Call findCurrentPlace and handle the response (first check that the user has granted permission). if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { val placeResponse = placesClient.findCurrentPlace(request) placeResponse.addOnCompleteListener { task -> if (task.isSuccessful) { val response = task.result for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) { Log.i( TAG, "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}" ) } } else { val exception = task.exception if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") } } } } else { // A local method to request required permissions; // See https://developer.android.com/training/permissions/requesting getLocationPermission() }
Java
// Use fields to define the data types to return. List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME); // Use the builder to create a FindCurrentPlaceRequest. FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields); // Call findCurrentPlace and handle the response (first check that the user has granted permission). if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request); placeResponse.addOnCompleteListener(task -> { if (task.isSuccessful()){ FindCurrentPlaceResponse response = task.getResult(); for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) { Log.i(TAG, String.format("Place '%s' has likelihood: %f", placeLikelihood.getPlace().getName(), placeLikelihood.getLikelihood())); } } else { Exception exception = task.getException(); if (exception instanceof ApiException) { ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + apiException.getStatusCode()); } } }); } else { // A local method to request required permissions; // See https://developer.android.com/training/permissions/requesting getLocationPermission(); }
關於可能性值的注意事項:
- 機率會提供相對機率,指出在單一要求中,該地點在傳回的地點清單中是否為最佳相符項目。您無法比較不同要求的可能性。
- 可能性值介於 0.0 到 1.0 之間。
舉例來說,如果要表示正確地點是地點 A 的可能性為 55%,地點 B 的可能性為 35%,回應就會包含兩個成員,地點 A 的可能性為 0.55,地點 B 的可能性為 0.35。
在應用程式中顯示出處資訊
如果應用程式會顯示從 PlacesClient.findCurrentPlace()
取得的資訊,則也須顯示出處資訊。請參閱歸屬說明文件。