地点详情

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

Places SDK for Android 为您的应用提供关于地点的丰富信息,包括地点的名称和地址、以纬度/经度坐标指定的地理位置、地点类型(如夜总会、宠物店、博物馆)等。如需访问特定地点的此类信息,您可以使用地点 ID,这是一个唯一标识地点的稳定标识符。

地点详情

Place 对象提供有关特定地点的信息。您可以通过以下方式获取 Place 对象:

请求地点时,您必须指定要返回哪些类型的地点数据。为此,请传递 List<Place.Field> 并指定要返回的数据类型。这是一项重要的考虑因素,因为这会影响每个请求的费用。由于地点数据结果不能为空,因此系统只会返回包含数据的地点结果(例如,如果请求的地点没有照片,photos 字段就不会出现在结果中)。您可以指定以下一个或多个字段:

  • Place.Field.ADDRESS
  • Place.Field.ADDRESS_COMPONENTS
  • Place.Field.BUSINESS_STATUS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.ICON_URL
  • Place.Field.ICON_BACKGROUND_COLOR
  • Place.Field.VIEWPORT
  • Place.Field.UTC_OFFSET
  • Place.Field.WEBSITE_URI

详细了解地点字段。如需详细了解地点数据请求的计费方式,请参阅用量和结算

使用以下方法从 Place 检索数据:

  • getAddress() - 地点的地址,采用人类可读懂的格式。
  • getAddressComponents() - 此地点的地址组成部分的 List。提供这些组件的目的在于提取地点的地址的结构化信息,例如查找地点所在的城市。请勿使用这些组件设置地址格式,而应调用 getAddress(),它可提供经过本地化的格式地址。
  • getBusinessStatus() - 地点的营业状态(如果是商家)。它可以包含以下值之一:OPERATIONALCLOSED_TEMPORARILYCLOSED PERMANENTLY
  • getAttributions() - 如果使用来自地点的数据,则必须向用户显示的提供方信息。
  • getID() - 地点的文本标识符。如需详细了解地点 ID,请参阅本页面的其余部分。
  • getLatLng() - 地点的地理位置,指定为纬度和经度坐标。
  • getName() – 地点的名称。
  • getOpeningHours() - 地点的 OpeningHours。调用 OpeningHours.getWeekdayText() 会返回一个字符串列表,这些字符串分别表示一周中每天的营业时间和打烊时间。调用 OpeningHours.getPeriods() 以返回 period 对象的列表,其中包含更详细的信息,等效于 getWeekdayText() 提供的数据。注意:如果某个地点一直营业,则时间段会以星期日的午夜来表示,并且 closeEvent 为 null。
  • getPhoneNumber() – 地点的电话号码。
  • getPhotoMetadatas() - 与地点相关联的照片关联的元数据,包括位图图片。
  • getPlusCode() - 此地点的 PlusCode 位置。
  • getPriceLevel() - 此地点的价格水平,以整数形式返回,其值介于 0(最便宜)到 4(最昂贵)之间。
  • getRating() - 地点的汇总评分,以浮点值形式返回,以用户总体评价为依据,其值范围为 1.0 到 5.0。
  • getTypes() - 描述此地点特征的地点类型列表。如需查看可用地点类型的列表,请参阅有关 Place 接口的文档。
  • getUserRatingsTotal() - 此地点的用户评分总数。
  • getIconUrl() - 表示地点类型的黑色图标遮罩的网址。
  • getIconBackgroundColor - 地点类型的图标背景颜色。
  • getUtcOffsetMinutes() - 世界协调时间偏移值(以分钟为单位)。
  • getViewport() - 视口,以 LatLngBounds 对象形式返回,可用于在地图上显示地点。如果地点的大小未知,可能会返回 null。
  • getWebsiteUri() - 地点网站的 URI(如果已知)。这是由与该地点关联的商家或其他实体维护的网站。如果没有已知网站,则会返回 null。
  • isOpen() - 表示该地点目前是否营业的布尔值。如果未指定时间,则现在采用默认值。仅当 Place.Field.UTC_OFFSETPlace.Field.OPENING_HOURS 均可用时才会返回 isOpen。为确保结果准确,请在原始地点请求中请求 Place.Field.BUSINESS_STATUSPlace.Field.UTC_OFFSET 字段。如果未收到请求,则系统会假定商家处于正常运营状态。 请参阅此视频,了解如何将 isOpen 与地点详情结合使用。

以下是一些简单示例:

Java


final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Kotlin


val name = place.name
val address = place.address
val location = place.latLng

      

按 ID 获取地点

地点 ID 是唯一标识地点的文本标识符。在 Places SDK for Android 中,您可以通过调用 Place.getId() 来检索地点 ID。地点自动补全服务还会返回与所提供的搜索查询和过滤条件匹配的每个地点的地点 ID。您可以存储地点 ID,稍后再用它来检索 Place 对象。

如需按 ID 获取地点,请调用 PlacesClient.fetchPlace(),并传递 FetchPlaceRequest

该 API 会在 Task 中返回 FetchPlaceResponseFetchPlaceResponse 包含与所提供的地点 ID 匹配的 Place 对象。

以下代码示例展示了如何调用 fetchPlace() 以获取指定地点的详细信息。

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

      

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

      

在应用中显示提供方说明

当应用显示地点信息时,还必须显示提供方说明。请参阅关于归因的文档。

更多关于地点 ID 的内容

Places SDK for Android 中使用的地点 ID 与 Places API 中使用的标识符相同。每个地点 ID 只能引用一个地点,但单个地点可以有多个地点 ID。还有其他情况可能会导致地点获得新的地点 ID。例如,如果商家搬到新地点,就可能发生这种情况。

当您通过指定地点 ID 来请求地点时,您可以确信自己在响应中始终会收到相同的地点(如果该地点仍然存在)。但请注意,响应中包含的地点 ID 可能与请求中的地点 ID 不同。

如需了解详情,请参阅地点 ID 概览