CleverSee: Vertical search vicinity query API-阿里云帮助中心

> Call the CommonQueryByScene API to search for nearby points of interest (POIs) using natural language.

Overview

API name: CommonQueryByScene

This API provides a natural language interface for a vicinity query. It supports searches for all types of POIs and returns structured data, including names, types, administrative divisions, addresses, distances from a central point, and business information. For specific business scenarios, specify a scene parameter to narrow the search scope, improving accuracy and response time (RT). If this parameter is omitted, the model intelligently identifies the scene.

This service is billed as "vicinity query" and charged per call. For details on pricing and metering, see Vertical search - Billing details.

Note

The default performance specifications for new subscriptions are 5 QPS. To request a higher limit, contact your account manager at least one week in advance.

API reference

Request parameters

Parameter	Description	Required	Default
query	The search keywords. This parameter supports natural language descriptions, such as "high-end hotels within 5km of Lingyin Temple in Hangzhou".	Yes	None
querySceneEnumCode	The search scene. Valid values are `hotels` for hotels, `attractions` for attractions, `restaurants` for restaurants, and `entertainment` for leisure and entertainment. If you do not provide this parameter, the model intelligently identifies the scene.	No	None
limit	The maximum number of results to return.	No	10
searchModel	The search mode. `single`: Simple mode, which returns a subset of fields, such as `name`, `types`, `address`, and `metadata`. `normal`: Normal mode, which returns all data fields.	No	normal

Response parameters

Parameter	Type	Description
requestId	string	The unique request ID.
data	list	A list of the returned locations.
data[].id	string	The internal ID.
data[].name	string	The name.
data[].latitude	string	The latitude.
data[].longitude	string	The longitude.
data[].types	string	The type. Multiple levels are separated by vertical bars (\|), for example, "Accommodation Service\|Hotel\|Five-star Hotel".
data[].typeCode	string	The type code.
data[].provinceName	string	The province.
data[].provinceCode	string	The province code.
data[].cityName	string	The city.
data[].cityCode	string	The city code.
data[].districtName	string	The district.
data[].districtCode	string	The district code.
data[].address	string	The full address.
data[].distanceMeter	string	The distance from the center point, in meters.
data[].metadata	object	Related business information.
data[].metadata.phone	string	The contact phone number. Multiple numbers are separated by vertical bars (\|).
data[].metadata.businessArea	string	The business area.
data[].metadata.mainTag	string	The main tag.
data[].metadata.score	string	The score.
data[].metadata.dailyOpeningHours	string	Today's opening hours.
data[].metadata.weeklyOpeningDays	string	The opening days of the week.
data[].metadata.averageSpend	string	The average spend, in CNY.
data[].images	list	A list of images.
data[].images[].title	string	The image title.
data[].images[].url	string	The image URL.

Examples

Request example

{
  "query": "high-end hotels within 5km of Lingyin Temple in Hangzhou",
  "querySceneEnumCode": "hotels"
}

Response example

{
  "requestId": "15A85F99-408F-5BFA-B617-0C7D3E732ABD",
  "data": [
    {
      "id": "B023B0BI3J",
      "name": "Amanfayun Hangzhou Hotel",
      "latitude": "30.234403",
      "longitude": "120.097327",
      "types": "Accommodation Service|Hotel|Five-star Hotel",
      "typeCode": "100102",
      "provinceName": "Zhejiang Province",
      "provinceCode": "330000",
      "cityName": "Hangzhou",
      "cityCode": "0571",
      "districtName": "Xihu District",
      "districtCode": "330106",
      "distanceMeter": "815",
      "address": "22 Fayun Lane, West Lake Scenic Area",
      "metadata": {
        "phone": "0571-8732****",
        "businessArea": "West Lake Tourist Area Core Zone",
        "mainTag": "Luxury",
        "score": "4.7",
        "dailyOpeningHours": null,
        "weeklyOpeningDays": null,
        "averageSpend": null
      },
      "images": [
        {
          "title": null,
          "url": "http://store.example.com/showpic/6ca3129317745e14b893e731408c9610"
        }
      ]
    },
    {
      "id": "B023B03721",
      "name": "Hangzhou Jiuli Yunsong Resort Hotel",
      "latitude": "30.244454",
      "longitude": "120.113209",
      "types": "Accommodation Service|Hotel|Five-star Hotel",
      "typeCode": "100102",
      "provinceName": "Zhejiang Province",
      "provinceCode": "330000",
      "cityName": "Hangzhou",
      "cityCode": "0571",
      "districtName": "Xihu District",
      "districtCode": "330106",
      "distanceMeter": "1204",
      "address": "18-8 Lingyin Road",
      "metadata": {
        "phone": "0571-8798****",
        "businessArea": "West Lake",
        "mainTag": "Luxury",
        "score": "4.8",
        "dailyOpeningHours": null,
        "weeklyOpeningDays": null,
        "averageSpend": null
      },
      "images": [
        {
          "title": "Lobby",
          "url": "http://store.example.com/showpic/e76beb3bedca3fe0375cef12742ea23e"
        }
      ]
    }
  ]
}

Note

The preceding response is an excerpt. The limit parameter, which defaults to 10, determines the number of items returned.

API calls

You can call this API using the Alibaba Cloud OpenAPI SDK and authenticate requests with an AK/SK. The service endpoints are as follows:

Region name	Region ID	Public endpoint
China (Zhangjiakou)	cn-zhangjiakou	iqs.cn-zhangjiakou.aliyuncs.com

For the Python SDK, install alibabacloud_iqs20240712. For the Java SDK, use the Maven coordinate com.aliyun:iqs20240712. We recommend that you use the latest version.

Python call example:

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="high-end hotels within 5km of Lingyin Temple in Hangzhou",
        query_scene_enum_code="hotels"
    )
)
resp = client.common_query_by_scene_with_options(request, {}, util_models.RuntimeOptions())
print(resp)

For code examples in Java and Go, and for MCP or Skill integration methods, see the "Integration Methods" section.

Error codes

HTTP status	Error code	Error message	Description
400	Throttling.User	Request was denied due to user flow control.	The user-level request limit was exceeded.
400	MissingParameter	Required parameter xxx is not found.	A required parameter is missing or invalid.
403	NotActivate	Please activate POI search service.	The POI search service is not activated.
403	NotAuthorised	Please authorize the AliyunIQSFullAccess privilege to the sub-account.	The sub-account is not authorized for the IQS service.
500	InternalServerError	An unexpected error occurred	An internal server error occurred.
500	ServiceUnavailable	Service unavailable	The service is currently unavailable.