查询

查询包提供了一组类，用于获取并解析单个 entity 的详细信息和富内容数据。其主要能力通过 Get Entity Detail 实现。

主要的查询相关类请参见 API reference。

通用请求参数

Lookup API 通过 entityClient.getDetailRequest() 构建请求，可设置以下通用参数：

方法	说明
setEntityIds(List entityIds)	地址或 POI 的 entity id 列表。支持单个查询或批量查询，传入多个 id 即可批量获取详情。必填
setDetailOptions(GetDetailOptions options)	详情选项，用于控制返回数据的详细程度。选填
setFacetParameters(FacetParameters facetParameters)	facet 相关参数，例如停车价格估算、关联 entity 等。选填
setLocation(double latitude, double longitude)	用户当前位置坐标。选填
setLocale(Locale locale)	响应内容的语言偏好，例如 `Locale.US`。选填

GetDetailOptions

通过 GetDetailOptions.builder() 构建后，经 setDetailOptions() 传入：

方法	说明
setDetailLevel(GetDetailOptions.EntityDetailLevel detailLevel)	返回数据的详细程度。`BASIC`：仅返回基本信息；`FULL`：返回所有可用信息
setShowAddressLines(Boolean showAddressLines)	设为 `true` 时，响应中返回分行格式化的 `address_lines`

FacetParameters

通过 FacetParameters.builder() 构建后，经 setFacetParameters() 传入：

方法	说明
setParkingParameters(ParkingParameters parameters)	停车参数，用于价格估算。`entry_time` 格式为 `yyyy-MM-ddTHH:mm` 或 `yyyy-MM-ddTHH:mmZ`（带 `Z` 表示 UTC，否则按本地时间处理）；`duration` 为停车时长（分钟），默认 60
setFacetFieldParameters(FacetFieldParameters parameters)	指定返回的结果 facet 类型
addAdditionalFacetAttribute(AdditionalFacetAttributeType type)	额外 facet 属性，如 `LINKED_ENTITY`（返回地址关联的 entity 列表）

Get Entity Detail

该能力用于获取某个 entity 的详细信息。其 id 通常来自上一次 entity 搜索返回的结果列表。entity 的详情结构与其类型（地址 address 或兴趣点 POI）相关。一般情况下，开发者需要根据返回的 entity 类型，分别处理地址详情和 POI 详情。

关键方法

方法	说明
setEntityIds(List entityIds)	地址或 POI 类型 entity 的唯一 id 列表，支持单个或批量查询。必填
setDetailOptions(GetDetailOptions options)	详情选项，例如设置 `detail_level` 为 `FULL` 获取完整信息。选填
setLocale(Locale locale)	响应内容的语言偏好。选填
GetDetailOptions.builder().setDetailLevel(GetDetailOptions.EntityDetailLevel level)	`BASIC` 返回基本信息，`FULL` 返回全部可用信息
GetDetailOptions.builder().setShowAddressLines(Boolean showAddressLines)	设为 `true` 时返回分行地址 `address_lines`

示例代码

Java

String addressEntityId = "Yz1zYW50YSBjbGFyYTtjbz11cztzZm49Z3JlYXQgYW1lcmljYSBwa3d5O2g9NDY1NTt6PTk1MDU0O3M9Y2E7aWQ9MTA2NTI0MDYxO2x0PTM3LjM5ODE1O2xuPS0xMjEuOTc3ODk7cmdjPWZhbHNlOwV6";

entityClient.getDetailRequest()
    .setEntityIds(Arrays.asList(addressEntityId))
    .asyncCall(new Callback<EntityGetDetailResponse>() {

        @Override
        public void onSuccess(EntityGetDetailResponse response) {
            // 以 JSON 格式打印响应
            LOG.info(EntityJsonConverter.toPrettyJson(response));

            List<Entity> detailEntities = response.getResults();
            for (Entity entity : detailEntities) {
                if (entity.getType() == EntityType.PLACE) {
                    LOG.info("Found Place: " + entity.getPlace().getName());
                } else if (entity.getType() == EntityType.ADDRESS) {
                    LOG.info("Found Address: " + entity.getAddress().getFormattedAddress());
                }
            }
        }

        @Override
        public void onFailure(Throwable t) {
            LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
        }
    });

Kotlin

val addressEntityId = "Yz1zYW50YSBjbGFyYTtjbz11cztzZm49Z3JlYXQgYW1lcmljYSBwa3d5O2g9NDY1NTt6PTk1MDU0O3M9Y2E7aWQ9MTA2NTI0MDYxO2x0PTM3LjM5ODE1O2xuPS0xMjEuOTc3ODk7cmdjPWZhbHNlOwV6"

entityClient.getDetailRequest()
    .setEntityIds(listOf(addressEntityId))
    .asyncCall(object : Callback<EntityGetDetailResponse> {

        override fun onSuccess(response: EntityGetDetailResponse) {
            // 以 JSON 格式打印响应
            Log.i("sdk", EntityJsonConverter.toPrettyJson(response))

            val detailEntities = response.results
            for (entity in detailEntities) {
                if (entity.type == EntityType.PLACE) {
                    Log.i("sdk", "Found Place: ${entity.place.name}")
                } else if (entity.type == EntityType.ADDRESS) {
                    Log.i("sdk", "Found Address: ${entity.address.formattedAddress}")
                }
            }
        }

        override fun onFailure(t: Throwable) {
            Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
        }
    })

响应示例

JSON

{
  "code": "SUCCESS",
  "message": "SUCCESS",
  "results": [
    {
      "id": "Yz1zYW50YSBjbGFyYTtjbz11cztzZm49Z3JlYXQgYW1lcmljYSBwa3d5O2g9NDY1NTt6PTk1MDU0O3M9Y2E7aWQ9MTA2NTI0MDYxO2x0PTM3LjM5ODE1O2xuPS0xMjEuOTc3ODk7cmdjPWZhbHNlOwV6",
      "type": "ADDRESS",
      "address": {
        "address_type": "STREET",
        "formatted_address": "4655 Great America Pkwy, Santa Clara CA 95054, USA",
        "house_number": "4655",
        "street": {
          "body": "great america",
          "type": "parkway",
          "formatted_name": "Great America Pkwy"
        },
        "city": "Santa Clara",
        "county": "Santa Clara",
        "state": "CA",
        "country": "USA",
        "postal_code": "95054",
        "location_type": "ADDRESS_POINT",
        "geo_coordinates": {
          "latitude": 37.39872,
          "longitude": -121.97663
        },
        "nav_coordinates": {
          "latitude": 37.39903,
          "longitude": -121.97727
        }
      }
    }
  ],
  "response_time": 21
}

Get Address Detail with Linked Entity

该能力用于获取某个地址（Address）的详细信息，并同时返回与之关联的 entity 列表。当一次请求中传入多个 entity id 时，该能力不会生效。