超区接口

验签、请求头、HMAC-SHA256 算法、多语言示例与通用开放对接一致，请先阅读 基础约定。

地址关键字检索

• 接口地址：/openapi/superzone/searchAddressByKeyword
• 请求方式：POST
• 说明：根据关键字做地址联想。searchMode 必填，仅允许 索引 或 地图（区分大小写）。

searchMode 说明

• 地图：直接调用地图检索接口。
• 索引：先查 Mongo 地址缓存；未命中时再调地图（此时返回体 searchMode 为 地图，表示实际数据来源）。

keyword 为空或缺省时，返回 code=200，result=null。请求体不可缺省（无 Body 可能 400）。

请求参数

字段	类型	必填	说明
keyword	String	是	检索关键字；服务端会去除空格。空则 result 为 null
searchMode	String	是	仅 索引 或 地图

请求示例

{
  "keyword": "武侯区天府大道",
  "searchMode": "索引"
}

响应字段

result 为 Map 结构：

字段	说明
searchMode	实际数据来源：索引（命中本地缓存）；地图（地图接口结果，含索引未命中回落地图）
data	字符串，内容为 JSON 数组的序列化结果（解析请以实际为准）

缓存/索引分支下单条候选大致包含：province、city、district、name、address、uid、location（含 lng/lat）等。

响应示例

{
  "code": 200,
  "message": "",
  "result": {
    "searchMode": "地图",
    "data": "[{\"name\":\"老君山风景名胜区\",\"address\":\"七里坪村21组\",\"pname\":\"河南省\",\"cityname\":\"洛阳市\",\"adname\":\"栾川县\",\"location\":\"111.657836,33.739153\",\"uid\":\"B017B01NH7\"}]"
  },
  "traceId": "20260425102849-xxx"
}

result.data 为字符串，需再 JSON.parse 后使用。地图侧单条字段以供应商返回为准。

错误码

code	场景
200	成功（result 可能为 null）
400	缺请求体、searchMode 为空，或不是 索引/地图
500	地图/检索无有效结果（ADDRESS_KEYWORD_SEARCH_FAILED）

---

超区公司列表查询

• 接口地址：/openapi/superzone/superZonePriceList
• 请求方式：POST
• 说明：按地址、省市区、目的地编码、计费方式等筛选超区配置列表。成功时 result 为分页对象（records、total、pageNo、 pageSize、pages）。

说明

与主站「聚美智数」queryPageListJum 入参含义对齐，服务端方法为 ISuperZoneService#queryPageListJum。

请求参数

字段	类型	必填	说明
address	String	否	搜索地址文本，用于关键字计费等匹配
addressResolution	String	否	解析后的地址；公里计费等会用到
lngLat	String	否	百度坐标，经度,纬度
gcj02LngLat	String	否	高德等坐标
province	String	条件	与 city 至少需有有效组合；均为空时返回 result=null
city	String	条件	同上
county	String	否	区/县
parsedData	String	否	用户搜索原文，缓存命中与关键字匹配使用
name	String	否	百度 POI 名称等
baiduAddress	String	否	百度地址
uid	String	否	地址缓存文档 id，用于命中缓存
destination	String	否	目的地区划编码串（逗号分隔省/市/区县码）
chargeMode	String	否	计费方式筛选
apiType	Integer	否	展示形态：1 时部分 remark 使用 <br/>；其它或空为 PC 样式

请求示例

{
  "address": "天府大道",
  "addressResolution": "四川省成都市武侯区天府大道",
  "province": "四川省",
  "city": "成都市",
  "county": "武侯区",
  "parsedData": "天府大道",
  "apiType": 0
}

响应字段

result（PageResult）：

字段	说明
records	JySuperZoneInfoVO 列表
total	筛选后条数
pageNo / pageSize / pages	分页信息

records[] 主要字段：

字段	说明
id	主键
destination / destinationDesc	目的站编码串 / 描述
chargeMode	计费方式（关键字计费、公里计费等）
keyword	关键字计费时的关键字配置
superzoneFee	超区费（公里计费等可能动态计算）
remark	说明（可能含 HTML）
companyInfoId / shortName / companyLogo	物流公司信息
stdKilos	标准公里数
centerAddr / centerLngLat / centerGcj02LngLat	中心点地址及坐标
isAuth	展示用认证标识

响应示例

{
  "code": 200,
  "message": "success",
  "result": {
    "records": [
      {
        "id": 1,
        "destination": "410000,410300,410324",
        "destinationDesc": "河南省洛阳市栾川县",
        "chargeMode": "关键字计费",
        "keyword": "老君山",
        "superzoneFee": "50.00",
        "remark": "超区配送范围",
        "companyInfoId": "101",
        "shortName": "某某物流",
        "stdKilos": 0
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 3000,
    "pages": 1
  }
}

业务说明

• 根据缓存或 province/city/county（及坐标反查区县）解析 destination；若最终 destination 仍为空，返回 code=200， result=null。
• 内部查询使用分页对象第 1 页、最多 3000 条拉取后再筛选；返回的 total 为筛选后的列表条数。

错误码

code	场景
200	成功（含 result 为 null 的业务空结果）
400	缺参、searchMode 非法等
500	关键字检索失败等