POI 圆形区域检索

接口说明

POI 圆形区域检索

输入示例：关键词：美食；圆心：39.915,116.404；半径：1000 米

返回示例：返回圆形范围内的美食 POI 列表，适合做附近搜索、周边设施分析。

请求地址

GEThttps://cloud.dtbgis.com/api/v1/poi/circle

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

每个 API Key 绑定已购接口与流量豆，调用成功扣减对应流量豆；调用失败（参数错误等）不扣流量豆。未开通该接口返回 403，流量豆不足返回 429。

请求参数

参数	必填	说明	示例 / 默认值
`query`	必填	搜索关键词，如"美食""酒店"	`美食`
`location`	必填	圆心坐标，格式 "lat,lng"（纬度在前）	`39.915,116.404`
`radius`	必填	检索半径，单位为米	`1000`
`tag`	可选	POI行业类型筛选标签	—
`page_num`	可选	页码，从0开始	`0`
`page_size`	可选	每页数量，最大20	`20`

请求示例

curl -H "X-API-Key: 你的API-Key" \
  "https://cloud.dtbgis.com/api/v1/poi/circle?query=%E7%BE%8E%E9%A3%9F&location=39.915%2C116.404&radius=1000"

import requests

resp = requests.get(
    "https://cloud.dtbgis.com/api/v1/poi/circle?query=%E7%BE%8E%E9%A3%9F&location=39.915%2C116.404&radius=1000",
    headers={"X-API-Key": "你的API-Key"},
)
print(resp.status_code, resp.json())

fetch("https://cloud.dtbgis.com/api/v1/poi/circle?query=%E7%BE%8E%E9%A3%9F&location=39.915%2C116.404&radius=1000", {
  headers: { "X-API-Key": "你的API-Key" }
})
  .then(r => r.json())
  .then(console.log);

返回结果说明

本接口返回统一 JSON 信封结构：

{
  "code": 200,
  "msg": "success",
  "data": { ... },
  "quota_remaining": 9999
}

字段	说明
`code`	业务状态码，`200` 表示成功
`msg`	状态描述，成功为 `success`
`data`	查询结果对象，字段见下方「`data` 字段说明」
`quota_remaining`	本次调用后剩余可用流量豆数量

data 为百度地图原始 JSON 透传，坐标系 BD-09（传入的 location 也需为 BD-09，纬度在前）。如需与厂商解耦的统一格式，请使用「POI 圆形区域检索 v2」（/api/v2/poi/circle）。

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": 0,
    "message": "ok",
    "total": 58,
    "results": [
      {
        "name": "某餐厅",
        "location": { "lat": 39.921, "lng": 116.432 },
        "address": "北京市东城区XX路XX号",
        "province": "北京市",
        "city": "北京市",
        "area": "东城区",
        "telephone": "(010)12345678",
        "uid": "abc123def456",
        "detail_info": {
          "tag": "美食;中餐厅",
          "overall_rating": "4.5",
          "price": "85"
        }
      }
    ]
  },
  "quota_remaining": 9995
}

`data` 字段说明

字段	类型	说明	示例
`status`	int	上游状态码，0 表示成功	`0`
`message`	string	上游状态描述	`ok`
`total`	int	检索总结果数	`58`
`results`	array	POI 结果列表	—
`uid`	string	POI 的 UID，可用于获取 AOI 边界	`abc123def456`
`name`	string	POI 名称	`某餐厅`
`address`	string	地址	`北京市东城区XX路XX号`
`location`	object	坐标（lat 纬度 / lng 经度，BD-09）	`{lat: 39.921, lng: 116.432}`
`province`	string	省份	`北京市`
`city`	string	城市	`北京市`
`area`	string	区县	`东城区`
`adcode`	string	行政区划编码（部分结果返回）	`110101`
`telephone`	string	电话	`(010)12345678`
`detail_info`	object	详情信息（scope=2 时返回）	—
`tag`	string	POI 类型标签	`美食;中餐厅`
`overall_rating`	string	总体评分	`4.5`
`price`	string	人均消费	`85`
`shop_hours`	string	营业时间	`10:00-22:00`
`distance`	int	距中心点距离（米，圆形检索时返回）	`521`

错误码

错误以统一结构返回：{"detail": {"code": 429, "msg": "..."}}

HTTP	含义	常见原因 / 处理
`400`	参数错误	缺少必填参数或格式不合法
`401`	鉴权失败	API Key 缺失、不存在、已停用或已过期
`403`	权限不足	该 API Key 未开通此接口，请购买流量豆
`429`	流量豆不足 / 限流	流量豆用完需续费；或超过速率（60 秒 200 次）
`404`	资源不存在	路径错误，或查询对象无数据
`503`	服务暂时不可用	服务暂时异常，请稍后重试

完整错误码见文档首页 · 错误码总览。