当前地点

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
选择平台Android iOS

使用 Places SDK for Android,您可以在设备当前报告的位置发现该地点。地点的示例包括本地商家、地图注点和地理位置。

权限

如需使用该库,您无需在应用清单中声明任何额外权限,因为该库会在其清单中声明它使用的所有权限。不过,如果您的应用使用 PlacesClient.findCurrentPlace(),则您必须在运行时请求位置权限

如果您的应用未使用 PlacesClient.findCurrentPlace(),请在清单中添加以下代码,明确移除库引入的 ACCESS_FINE_LOCATION 权限:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    ...
</manifest>

详细了解权限,并考虑使用 EasyPermissions 开始使用该功能。

获取当前位置

如需查找本地商家或设备目前所在的位置,请按以下步骤操作:

  1. 调用 ContextCompat.checkSelfPermission 以检查用户是否已授予访问其设备位置信息的权限。您的应用还必须包含用于提示用户授予权限和处理结果的代码。 如需了解详情,请参阅请求应用权限
  2. 创建 FindCurrentPlaceRequest,并传递 Place.FieldList,指定您的应用应请求的地点数据类型。
  3. 调用 PlacesClient.findCurrentPlace(),并传递您在上一步中创建的 FindCurrentPlaceRequest
  4. FindCurrentPlaceResponse 获取 PlaceLikelihood 列表。

这些字段与地点搜索结果相对应,分为三个结算类别:基本结算、联系人结算和氛围结算。基本字段采用基本费率计费,不会产生额外费用。“联系人”和“氛围”字段以较高费率结算。如需详细了解地点数据请求的计费方式,请参阅用量和结算

该 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 是正确地点的可能性为 55%,地点 B 是正确地点的可能性为 35%,地点响应包含两个成员:地点 A 的可能性为 0.55,地点 B 的可能性为 0.35。

在应用中显示提供方说明

当您的应用显示通过 PlacesClient.findCurrentPlace() 获取的信息时,还必须显示提供方说明。请参阅关于归因的文档。