目前位置

透過集合功能整理內容 你可以依據偏好儲存及分類內容。
選取平台: Android iOS

使用 Places SDK for Android,即可在裝置目前回報的位置探索地點。例如當地商家、搜尋點和地理位置

權限

如要使用這個程式庫,您無須在應用程式資訊清單中宣告任何其他權限,因為該程式庫在資訊清單中宣告了所有權限。不過,如果您的應用程式使用 PlacesClient.findCurrentPlace(),則必須在執行階段要求位置存取權

如果您的應用程式未使用 PlacesClient.findCurrentPlace(),請將下列內容加入資訊清單,明確移除程式庫提供的 ACCESS_FINE_LOCATIONACCESS_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 開始使用。

取得目前位置

如要找出當地商家或裝置目前所在的位置,請按照下列步驟操作:

  1. 呼叫 ContextCompat.checkSelfPermission 以確認使用者是否已授權存取其裝置位置資訊。應用程式也必須包含程式碼,以便提示使用者授予權限並處理結果。詳情請參閱「要求應用程式權限」。
  2. 建立 FindCurrentPlaceRequest,傳遞 Place.FieldList,並指定應用程式應要求的地點資料類型。
  3. 呼叫 PlacesClient.findCurrentPlace(),並傳遞您在上一個步驟中建立的 FindCurrentPlaceRequest
  4. FindCurrentPlaceResponse 取得 PlaceLikelihood 清單。

欄位會對應至 Place Search 結果,分為三種計費類別:「Basic」、「Contact」和「Atmosphere」。基本欄位是按基本費率計費,不會產生額外費用。「Contact」和「Atmosphere」欄位會以較高的費率計費。如要進一步瞭解地點資料要求的計費方式,請參閱用量與帳單

API 會在 Task 中傳回 FindCurrentPlaceResponseFindCurrentPlaceResponse 包含 PlaceLikelihood 物件清單,代表裝置可能所在的位置。針對每個地點,結果包含該位置是否代表該地點的可能性。如果特定裝置位置沒有已知的已知位置,清單就會是空白。

您可以呼叫 PlaceLikelihood.getPlace() 以擷取 Place 物件,以及呼叫 PlaceLikelihood.getLikelihood() 以取得地點的可能性評分。值越大,表示地點的可能性越高。

以下程式碼範例會擷取裝置最有可能所在的地點清單,並記錄每個地點的名稱和可能性。

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

      

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

      

可能值的注意事項:

  • 針對單一要求,傳回地點在傳回地點清單中的可能性,最可能性。你無法比較不同要求的可能性。
  • 可能性的值必須介於 0.0 到 1.0 之間。

舉例來說,如果正確位置的可能性為 A,地點為 A 的可能性為 55%,地點為 B 的機率為 35%,回應就會包含 2 位成員,地點 A 為 0.55,地點 B 的可能性為 0.35。

在應用程式中顯示歸因方式

當應用程式顯示從 PlacesClient.findCurrentPlace() 取得的資訊時,應用程式也必須顯示出處。請參閱歸因說明文件。