腾讯地图API如何通过省市查区县？

Question

如何通过腾讯地图API根据指定的省、市名称查询下属区县列表？常见问题包括：API接口是否直接支持行政区划层级查询？请求参数中adcode的获取方式不明确，导致无法精准定位目标区域。此外，模糊搜索可能返回非结构化结果，难以提取标准区县名称。许多开发者反馈，未正确使用`region_code`或未开启行政区划数据返回选项，导致响应中缺少区县级信息。如何构造合规请求以获取完整的下级行政区划数据？

Answer 1

一、腾讯地图API行政区划查询基础概念

腾讯地图开放平台提供了丰富的地理信息服务，其中行政区划查询是常见需求之一。开发者常需根据指定的省或市名称获取其下属区县列表。然而，该功能并非通过单一接口直接暴露，而是依赖于多个服务模块协同完成。

核心API包括：

• 地点搜索（Place Search）：支持关键词模糊匹配，但返回结果可能非结构化。
• 逆地址解析（Reverse Geocoding）：适用于坐标转行政区信息。
• 行政区划接口（District Search API）：专门用于获取行政层级数据，支持省、市、区/县三级结构化输出。

目前，腾讯地图官方推荐使用 District Search API 实现精准的下级行政区划查询。

二、API是否支持层级化行政区划查询？

是的，腾讯地图提供 District Search API 支持多级行政区划查询，可通过设置 level 参数控制返回层级：

Level 值	对应行政区级别
1	国家
2	省份
3	城市
4	区/县
5	城镇/街道

例如，若要查询“广州市”下的所有区县，应将父级城市的 adcode 作为参数传入，并设置 level=4。

三、adcode 的获取方式与 region_code 的作用解析

adcode 是腾讯地图中标识行政区的唯一编码，如北京市为 110000，上海市为 310000。准确获取目标省市的 adcode 是发起有效请求的前提。

获取 adcode 的方法如下：

1. 调用 Place Suggestion API 进行关键词提示，输入“广州”，返回建议列表中包含对应的 adcode。
2. 使用 District Search API 查询省级单位，再逐层下钻到市级，提取对应节点的 adcode。

此外，region_code 并非腾讯地图标准参数，实际应使用 district_id 或 adcode 作为区域标识符。误用会导致请求失败或数据缺失。

四、构造合规请求以获取完整区县列表

以下是合规请求示例，用于查询广州市下属区县：

GET https://apis.map.qq.com/ws/district/v1/getchildren?
key=YOUR_API_KEY
&id=440100
    

说明：

• key：开发者在腾讯地图开放平台申请的密钥。
• id：即 adcode，此处 440100 表示广州市。

响应示例（简化）：

{
  "status": 0,
  "result": [
    {
      "id": "440103",
      "name": "荔湾区",
      "fullname": "广东省广州市荔湾区",
      "center": {"lat": 23.119, "lng": 113.264}
    },
    {
      "id": "440104",
      "name": "越秀区",
      "fullname": "广东省广州市越秀区",
      "center": {"lat": 23.123, "lng": 113.281}
    }
  ]
}
    

五、常见问题分析与解决方案流程图

开发者常遇到的问题及处理逻辑可归纳为以下流程：

graph TD
            A[开始: 输入省/市名称] --> B{是否有adcode?}
            B -- 否 --> C[调用Place Suggestion API获取adcode]
            B -- 是 --> D[调用District Search API]
            C --> D
            D --> E{响应是否含区县数据?}
            E -- 否 --> F[检查level参数是否设为4]
            F --> G[确认API密钥权限是否开启行政区服务]
            G --> D
            E -- 是 --> H[解析result数组提取区县name和adcode]
            H --> I[完成]

六、提升数据结构化程度的实践建议

为避免模糊搜索带来的非结构化问题，建议遵循以下最佳实践：

• 优先使用 District Search API 而非通用搜索接口。
• 建立本地 adcode 缓存表，减少重复请求。
• 对返回结果进行标准化清洗，统一命名格式（如去除“市辖区”等冗余项）。
• 结合腾讯地图的 行政区划树形结构文档 预加载全国层级关系。
• 在前端展示时，采用级联选择器（Cascader）提升用户体验。

对于大规模应用，可设计后台定时任务同步最新行政区划变更，确保数据时效性。