CleverSee-垂域搜索周边查询接口-AI 原生搜索 CleverSee-阿里云帮助中心

> 调用 CommonQueryByScene 接口，以自然语言检索周边地点（POI）信息。

一、接口说明

接口名称：CommonQueryByScene

能力说明：周边查询的自然语言接口，支持自然语言查询全量 POI 类型，返回名称、类型、行政区划、地址、距中心点距离及商业信息等结构化字段。业务场景明确时，可通过场景参数限定查询范围，从而在准确度和 RT 上获得更好的效果；也可忽略场景参数，交由模型智能识别。

计量方式为「周边查询」，按次计费，单价与计量口径详见垂域查询-计费说明。

说明

性能规格新购默认开通：5QPS。如需申请更高规格，请提前一周联系商务经理协助处理。

二、接口定义

请求参数

参数名	含义及规则	是否必须	缺省值
query	搜索关键词，支持自然语言描述，例如「杭州灵隐寺附近 5km 的高档酒店」。	必填	无
querySceneEnumCode	搜索场景枚举。hotels：酒店场景；attractions：景点场景；restaurants：餐厅场景；entertainment：休闲娱乐场景。不传则由模型智能识别。	非必填	无
limit	返回结果的最大数量限制。	非必填	10
searchModel	检索模式。single：精简模式，仅返回 name、types、address、metadata 等部分字段；normal：正常模式，返回全量数据。	非必填	normal

返回参数

参数名	类型	说明
requestId	string	请求唯一 ID
data	list	返回的地点数据列表
data[].id	string	内部标识号
data[].name	string	名称
data[].latitude	string	纬度
data[].longitude	string	经度
data[].types	string	类型，多级类型以竖线分隔，例如「住宿服务\|宾馆酒店\|五星级宾馆」
data[].typeCode	string	类型编码
data[].provinceName	string	所属省份
data[].provinceCode	string	所属省份编码
data[].cityName	string	所属城市
data[].cityCode	string	所属城市编码
data[].districtName	string	所属区域
data[].districtCode	string	所属区域编码
data[].address	string	详细地址
data[].distanceMeter	string	距中心点距离，单位米
data[].metadata	object	相关商业信息
data[].metadata.phone	string	联系电话，多个号码以竖线分隔
data[].metadata.businessArea	string	所属商圈
data[].metadata.mainTag	string	主标签
data[].metadata.score	string	评分
data[].metadata.dailyOpeningHours	string	今日营业时间
data[].metadata.weeklyOpeningDays	string	每周营业时间
data[].metadata.averageSpend	string	平均花费，单位元
data[].images	list	图片列表
data[].images[].title	string	图片名称
data[].images[].url	string	图片链接

三、示例

请求示例

{
  "query": "杭州灵隐寺附近5km的高档酒店",
  "querySceneEnumCode": "hotels"
}

响应示例

{
  "requestId": "15A85F99-408F-5BFA-B617-0C7D3E732ABD",
  "data": [
    {
      "id": "B023B0BI3J",
      "name": "杭州法云安缦酒店",
      "latitude": "30.234403",
      "longitude": "120.097327",
      "types": "住宿服务|宾馆酒店|五星级宾馆",
      "typeCode": "100102",
      "provinceName": "浙江省",
      "provinceCode": "330000",
      "cityName": "杭州市",
      "cityCode": "0571",
      "districtName": "西湖区",
      "districtCode": "330106",
      "distanceMeter": "815",
      "address": "西湖景区法云弄22号",
      "metadata": {
        "phone": "0571-8732****",
        "businessArea": "西湖旅游区中心片区",
        "mainTag": "豪华型",
        "score": "4.7",
        "dailyOpeningHours": null,
        "weeklyOpeningDays": null,
        "averageSpend": null
      },
      "images": [
        {
          "title": null,
          "url": "http://store.example.com/showpic/6ca3129317745e14b893e731408c9610"
        }
      ]
    },
    {
      "id": "B023B03721",
      "name": "杭州九里云松度假酒店",
      "latitude": "30.244454",
      "longitude": "120.113209",
      "types": "住宿服务|宾馆酒店|五星级宾馆",
      "typeCode": "100102",
      "provinceName": "浙江省",
      "provinceCode": "330000",
      "cityName": "杭州市",
      "cityCode": "0571",
      "districtName": "西湖区",
      "districtCode": "330106",
      "distanceMeter": "1204",
      "address": "灵隐路18-8号",
      "metadata": {
        "phone": "0571-8798****",
        "businessArea": "西湖",
        "mainTag": "豪华型",
        "score": "4.8",
        "dailyOpeningHours": null,
        "weeklyOpeningDays": null,
        "averageSpend": null
      },
      "images": [
        {
          "title": "大厅",
          "url": "http://store.example.com/showpic/e76beb3bedca3fe0375cef12742ea23e"
        }
      ]
    }
  ]
}

说明

上述响应示例为节选，实际返回条数由请求参数 limit 决定（缺省 10 条）。

四、接口调用

本接口通过阿里云 OpenAPI SDK 调用，使用阿里云 AK/SK 认证。服务接入点如下：

地域名称	地域 ID	公网接入地址
华北 3（张家口）	cn-zhangjiakou	iqs.cn-zhangjiakou.aliyuncs.com

Python SDK 需安装 alibabacloud_iqs20240712，Java SDK 使用 Maven 坐标 com.aliyun:iqs20240712（建议使用最新版本）。

Python 调用示例：

from alibabacloud_iqs20240712.client import Client as IQS20240712Client
from alibabacloud_iqs20240712.models import CommonAgentQuery
from alibabacloud_iqs20240712 import models as iqs20240712_models
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models

config = open_api_models.Config(
    access_key_id='$YOUR_ACCESS_KEY',
    access_key_secret='$YOUR_ACCESS_SECRET'
)
config.endpoint = 'iqs.cn-zhangjiakou.aliyuncs.com'
client = IQS20240712Client(config)

request = iqs20240712_models.CommonQueryBySceneRequest(
    body=CommonAgentQuery(
        query="杭州灵隐寺附近5km的高档酒店",
        query_scene_enum_code="hotels"
    )
)
resp = client.common_query_by_scene_with_options(request, {}, util_models.RuntimeOptions())
print(resp)

Java、Go 版本示例代码以及 MCP / Skill 接入方式，请参考「接入方式」章节。

五、错误码

HTTP Status	错误码	错误信息	说明
400	Throttling.User	Request was denied due to user flow control.	用户限流错误
400	MissingParameter	Required parameter xxx is not found.	请求参数错误
403	NotActivate	Please activate POI search service.	未开通 POI 搜索服务
403	NotAuthorised	Please authorize the AliyunIQSFullAccess privilege to the sub-account.	子账号未被授权 IQS 权限
500	InternalServerError	An unexpected error occurred	系统内部错误
500	ServiceUnavailable	Service unavailable	服务不可用