Skip to content

搜索返回对象

当 SearchResponse 对应 文本搜索、附近搜索、分类搜索（列表） 或 POI 详情 等 Hybrid 场景时，列表与详情的 body 为 SearchBody.EntitySearch，其值为 TN Entity SDK 的 EntitySearchResponse。无论 provider 为 google 还是 tn，集成方均使用同一 Kotlin 类型与字段约定；本文说明根对象字段、响应码 与 results[] 中 Entity 的结构。

更完整的接入步骤见 快速接入 中 §2.3 entitySearchOrNull() 的读取范式及各搜索 Builder 章节。

与自动补全区分

operation == "autocomplete" 时 body 为 SearchBody.Autocomplete，不是 本文所述的 EntitySearch；results[] 为建议项而非完整 POI Entity。字段与集成方式见 推荐返回对象。请按 operation 分支解析，不要混用两套 parser。

相关文档

文档 内容
快速接入 SearchService / SearchClient、线程与生命周期、各请求 Builder
返回对象 autocomplete、EntitySuggestionPredictionResponse、建议项 results[]
请求参数 请求 Builder、Google/TN 路径与字段对照

外层 SearchResponse 与 SearchBody

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
data class SearchResponse(
    val provider: String,       // "google" | "tn"
    val operation: String,      // 如 "textSearch" | "detail" | "categorySearch"
    val body: SearchBody        // 见 api/SearchBody.kt
)

sealed interface SearchBody {
    data class EntitySearch(val value: EntitySearchResponse) : SearchBody  // 列表/详情
    data class Autocomplete(val value: EntitySuggestionPredictionResponse) : SearchBody
    data class Sdk(val value: Any) : SearchBody  // TN-only SDK 类型
}
读者场景 说明
集成方 读 response.code（与 EntitySearchResponse.code 一致）；POI 列表/详情数据用 response.entitySearchOrNull()?.results。
列表 / 详情 SearchBody.EntitySearch.value 即 TN SDK EntitySearchResponse；Google 与 TN 同一 operation 下类型一致。
需要 JSON 自行 Gson().toJson(response.entitySearchOrNull())；search-service 不再对外序列化 body 字符串。

body 根对象（列表 / 详情）

根对象字段与 TN Entity SDK 的 EntitySearchResponse 一致：

字段 类型 必填 说明
code int ✓ 12200 表示成功；完整表见下节
message string ✓ 状态说明
results Entity[] ✓ 搜索结果；详情时长度通常为 1
responseTime int ✓ 毫秒
responseType string ✓ CLOUD | ONBOARD
referenceId string 请求关联 ID
searchMetadata object TN 常见；Google 路径通常无
hasMore boolean TN 分页提示
resultsFacet object TN 聚合 facet
paginationContext object nextPageContext / prevPageContext

响应码（code）

值 含义
12200 SUCCESS
12204 NO_CONTENT
12206 PARTIAL_SUCCESS
12301 ENTITY_MOVED
12400 INVALID_REQUEST
12401 INVALID_APIKEY_OR_SIGNATURE
12404 ENTITY_NOT_FOUND
12405 METHOD_NOT_SUPPORTED
12500 INTERNAL_SERVER_ERROR
12501 NOT_IMPLEMENTED
12504 SERVICE_TIMEOUT_ERROR
12505 SERVICE_DATA_ERROR

results[]：Entity

与 SDK com.telenav.sdk.entity.model.base.Entity 对齐，字段名 camelCase。

type: "PLACE"（Google 列表/详情当前仅产出此类型）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "id": "P-G-ChIJxxxx",
  "type": "PLACE",
  "distance": 7164.0,
  "place": {
    "place_id": "P-G-ChIJxxxx",
    "name": "Starbucks",
    "categories": [{ "id": "241", "name": "Coffee Houses" }],
    "address": {
      "formattedAddress": "5600 Scotts Valley Dr, Scotts Valley CA 95066, USA",
      "country": "USA",
      "geoCoordinates": { "latitude": 37.06147, "longitude": -122.00706 },
      "navCoordinates": { "latitude": 37.06147, "longitude": -122.00706 }
    },
    "phoneNumbers": ["18314409801"],
    "permanentlyClosed": false
  },
  "facets": {
    "openHours": {
      "regularOpenHours": [{ "day": "1", "openTime": [{ "from": "05:00:00", "to": "18:00:00" }] }],
      "open24hours": false,
      "openNow": true
    },
    "rating": [{ "averageRating": 3.5, "totalCount": 50 }],
    "priceInfo": { "priceLevel": 1, "priceDescription": "" },
    "photo": { "photoItems": [] },
    "review": { "reviews": [] },
    "evConnectors": null,
    "chargeStations": null
  }
}

type: "ADDRESS"（TN 常见；Google 路径列表/详情通常不返回）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "id": "Yz1Mb3MgR2F0b3M7...",
  "type": "ADDRESS",
  "distance": 274.0,
  "address": {
    "addressType": "STREET",
    "formattedAddress": "Pierce Rd, Los Gatos CA 95033, USA",
    "geoCoordinates": { "latitude": 37.12602, "longitude": -121.99036 },
    "navCoordinates": { "latitude": 37.12602, "longitude": -121.99036 }
  }
}

路径差异（维护参考）

集成方只需按上文字段读取 EntitySearchResponse；下表供 SDK 维护与排障参考。

来源 如何得到统一 body
Google 增强结果源原始 JSON → EntitySearchBodyParser.fromGoogleRawJson() 反序列化为 EntitySearchResponse（详情 result 归一为 results[0]）
TN EntityClient → EntitySearchResponse 直接透传
维护参考 说明
googleplaceuikit/public/Utils.js Google 路径字段映射：createEntityResponse + transformPlaceData
telenav-entity-hybrid TN 路径：EntitySearchResponse / Entity

与 TN REST 文档的差异（故意保留）

项 本文规范 TN REST 文档示例
字段命名 camelCase snake_case
code int 12200 有时为 "SUCCESS" 字符串
Google ID P-G- 前缀 TN 云 ID 无此前缀

集成方应使用 本文规范 + SDK Entity Gson，不要混用 TN REST snake_case 示例直接解析 Google 返回。

JSON 示例（最小成功列表）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "code": 12200,
  "message": "Success",
  "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "results": [
    {
      "id": "P-G-ChIJxxxx",
      "type": "PLACE",
      "distance": 1200.0,
      "place": {
        "place_id": "P-G-ChIJxxxx",
        "name": "Example Cafe",
        "categories": [{ "id": "241", "name": "Coffee Houses" }],
        "address": {
          "formattedAddress": "1 Main St, City ST 12345, USA",
          "geoCoordinates": { "latitude": 37.0, "longitude": -122.0 }
        },
        "phoneNumbers": [],
        "permanentlyClosed": false
      },
      "facets": {
        "openHours": null,
        "rating": [{ "averageRating": 4.2, "totalCount": 10 }],
        "priceInfo": { "priceLevel": 2, "priceDescription": "" },
        "photo": { "photoItems": [] },
        "review": { "reviews": [] }
      }
    }
  ],
  "responseTime": 102,
  "responseType": "CLOUD"
}

TN-only 接口（SearchBody.Sdk）

以下接口经 SearchResponse 返回，provider 为 tn，body 为 SearchBody.Sdk(对应 Entity SDK 类型)，不要求与 EntitySearchResponse 完全一致：

operation SDK 响应类型（示意）
rgc EntitySearchResponse
wordSuggestion EntityWordPredictionResponse
categories EntityGetCategoriesResponse
discoverCategories EntityDiscoverCategoryResponse
discoverBrands EntityDiscoverBrandResponse
discoverPlaces EntityDiscoverPlaceResponse
searchByExit / searchByRestArea EntitySearchByExitResponse
brandSearch / polygonSearch EntitySearchResponse

Hybrid 模式下 textSearch、categorySearch、detail 等仍须符合本文 EntitySearch 规范。

详情页图片 URL 由 entityDetail 返回的 body（Entity / place.photos 等）提供，不提供单独的 loadPhoto API。

推荐返回对象

当 SearchResponse.operation == "autocomplete"（地点自动补全 / Suggestion）时，body 对应 SearchBody.Autocomplete，其值为 TN Entity SDK 的 EntitySuggestionPredictionResponse。无论 provider 为 google 还是 tn，集成方均使用同一类型与字段约定；本文说明 results[] 中每条推荐项的字段与选中后的下一步操作。

更完整的接入步骤见 快速接入 中 §3.12 地址自动补全 与 §2.3 中 autocompleteOrNull() 的读取范式。

说明

Autocomplete 的 results[] 元素类型为 AutocompleteSuggestion（建议项），不是 文本/分类搜索里的完整 POI Entity。请按 operation 分支解析 body，不要对 Autocomplete 响应复用列表 POI 的解析逻辑。

相关文档

文档 内容
快速接入 SearchService / SearchClient、suggestionPredictionRequest、线程与生命周期
请求参数 请求 Builder、Google/TN 路径与字段对照
返回对象 entitySearchOrNull()、EntitySearchResponse 与完整 Entity

外层 SearchResponse

与列表、详情等接口一致，最外层仍使用统一的 SearchResponse：

字段 说明
code 与 body 内 code 一致（如 12200 表示成功）
provider "google" 或 "tn"，表示本次结果最终来源
operation 固定为 "autocomplete"
body 类型化载荷；集成方应使用 autocompleteOrNull() 读取 EntitySuggestionPredictionResponse（若误用 entitySearchOrNull() 会得到 null）

body 根对象

根对象字段与 TN Entity SDK 的 EntitySuggestionPredictionResponse 一致：

字段 类型 必填 说明
code int ✓ 12200 表示成功；其余错误码与 返回对象 中响应码表一致
message string ✓ 状态说明
results AutocompleteSuggestion[] ✓ 推荐项列表（下文详述）；不是 POI Entity 数组
responseTime long ✓ 耗时（毫秒）
responseType string ✓ CLOUD 或 ONBOARD
referenceId string 可选，请求关联 ID

results[]：推荐项（AutocompleteSuggestion）

每条推荐项描述一行可展示、可点击的候选，分为 ENTITY（可选中具体地点）与 QUERY（仅查询串续搜）两类。

字段 类型 说明
type string ENTITY：可选中地点；QUERY：仅关键词，无绑定地点
label string 展示用主文案（含地址时常为「名称, 地址」）；QUERY 类型下为续搜关键词
displayName string 主标题（通常与 label 相同或为其前缀）
category object 可选，形如 { "id", "name" }（TN 路径较常见）
entity object 仅当 type == "ENTITY" 时非空；见下节

entity（轻量对象）

当 results[].type == "ENTITY" 时，entity 非空。集成方可依赖以下字段完成列表展示与下一步请求：

字段 类型 必填 说明
id string ✓ 地点唯一 ID。Google：P-G-{placeId}，用于 getDetailRequest().setEntityIds(...)；TN：云端或本地 entity id
label string ✓ 展示与续搜文案；可作 searchRequest().setQuery(label) 的 query
type string PLACE 或 ADDRESS（Google 归一化多为 PLACE）
displayName string 主标题，常与 label 同义或为其前缀
address string 格式化地址（Google 可能为空字符串）
distance number 距搜索中心米数（Google 可能为 0 或省略）
geoCoordinates { latitude, longitude } 可选，地图扎点
navCoordinates { latitude, longitude } 可选

集成建议

用户选中场景 建议下一步
type == "ENTITY" 且 entity.id 非空 优先 getDetailRequest().setEntityIds(listOf(entity.id)) 拉详情
type == "ENTITY"，仅需关键词续搜 searchRequest().setQuery(entity.label)（或外层 results[].label）
type == "QUERY"（无 entity） searchRequest().setQuery(results[].label)

type == "QUERY" 时 entity 为 null 或省略；此时以 results[].label 为唯一必选展示与续搜字段。

JSON 示例

ENTITY 项保证含 entity.id 与 entity.label；其余字段可能为空或省略。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "code": 12200,
  "message": "SUCCESS",
  "results": [
    {
      "type": "ENTITY",
      "label": "Starbucks, 1 Main St, Paris",
      "displayName": "Starbucks",
      "entity": {
        "id": "P-G-ChIJxxxx",
        "type": "PLACE",
        "displayName": "Starbucks",
        "label": "Starbucks",
        "address": "",
        "distance": 0,
        "geoCoordinates": { "latitude": 48.86, "longitude": 2.35 }
      }
    },
    {
      "type": "QUERY",
      "label": "coffee shop",
      "displayName": "coffee shop"
    }
  ],
  "responseTime": 320,
  "responseType": "CLOUD"
}

与列表/详情 body 的差异

项目 textSearch / detail 等 autocomplete
results[] 元素 完整 Entity（含 place / facets 等） AutocompleteSuggestion（轻量推荐项）
规范文档 返回对象 本文

前端务必根据 operation 分支选择 entitySearchOrNull() 或 autocompleteOrNull()，不要对 Autocomplete 使用 POI 列表专用 parser。