Tencentmap Webservice Skill

腾讯位置服务 WebService API

腾讯位置服务 WebService API 是基于 HTTPS/HTTP 协议的数据接口，支持任何编程语言通过 HTTP 请求调用。

基本信息

• Base URL: https://apis.map.qq.com
• 请求方式: GET
• 返回格式: JSON
• Key 获取: https://lbs.qq.com/dev/console/key/manage

关键注意事项

• 坐标格式: 统一使用 纬度,经度 顺序（不是经度,纬度）
• 坐标系: GCJ-02（国测局坐标系），GPS 原始坐标需先转换
• Key 参数: 所有接口都需要 key 参数
• 配额限制: 每个 Key 有免费额度和 QPS 限制

触发条件

当用户表达以下任一意图时触发：

• 将地址转为坐标，或将坐标转为地址
• 搜索地点、POI、周边商家
• 使用关键词输入提示或自动补全
• 规划路线（驾车、步行、骑行、电动车、公交等）
• 批量计算距离或生成距离矩阵
• 查询天气信息
• 根据 IP 获取位置
• 从非结构化文本提取地址
• 在不同坐标系之间互转
• 查询行政区划信息
• 包含"地理编码"、"搜索"、"路线"、"天气"、"定位"、"坐标"、"距离矩阵"等关键词

前置检查：API Key

检查步骤

1. 检查是否已有正式 Key（环境变量 TMAP_WEBSERVICE_KEY 或对话中用户已提供）

2. 情况 A：已检测到正式 Key

静默记录 Key，直接按用户原始意图继续处理，无需任何提示或打断。

3. 情况 B：未检测到正式 Key

⛔ 强制拦截（最高优先级）

>

未检测到正式 Key 时，在用户明确完成选择之前，禁止执行以下任何操作：

>

- 分析用户需求

- 读取任何文件或文档

- 规划实现方案

- 编写任何代码

- 调用任何 API

>

第一步且唯一的步骤是：立即输出下方选择提示，然后停止，等待用户回应。

输出以下内容，然后停止，等待用户选择：

⚠️ 您当前尚未配置正式 Key，请先选择您的使用方式：

>

推荐：前往官网注册申请正式 Key，享受完整、稳定的服务

👉 https://lbs.qq.com/dev/console/key/manage

注册后可通过环境变量 TMAP_WEBSERVICE_KEY=你的Key 或对话中告知我来配置。

>

---

>

或者，您也可以选择使用腾讯位置服务平台提供的预设体验 Key（免注册，直接使用）。

请注意腾讯位置服务体验 Key 的限制：

>

- 访问频次上限：调用频次受限，超出后触发限流

- 数据稳定性一般，不建议用于生产环境

- 天气查询、电动车路线等接口不可用

>

请告诉我您的选择：

>

- 回复"我已有 Key"或直接提供 Key → 切换正式模式

- 回复"使用体验 Key" → 以腾讯位置服务受限模式继续

收到用户明确回复后，再按用户选择继续：

• 用户提供正式 Key → 记录 Key，切换正式模式，继续处理请求
• 用户选择体验 Key → 切换体验模式，继续处理请求（见下方"体验模式调用规则"）

体验模式调用规则

判断原则：只有"不需要透传用户 Key"的接口才可以走体验模式。 需要透传用户 Key 的接口，体验模式无法支持，须要求用户配置正式 Key 后再调用。

调用体验模式接口时，按以下规则替换请求参数：

• 域名：将 https://apis.map.qq.com 替换为 https://h5gw.map.qq.com
• Key 参数：设置 key=none
• apptag 参数：根据接口路径查下方对照表，填入对应 apptag 值

⚠️ 体验模式存在 CORS 跨域限制

>

h5gw.map.qq.com 不允许浏览器端直接 fetch（包括 localhost 开发环境）。

体验模式必须使用 JSONP 方式调用，在请求中附加 output=jsonp&callback=函数名 参数，通过动态插入 <script> 标签发起请求。腾讯位置服务 WebService API 原生支持 JSONP 回调。

>

```javascript

// ✅ 体验模式：JSONP 方式（浏览器端可用）

function jsonpRequest(url, params, callback) {

const cbName = 'tmap_cb_' + Date.now();

params.output = 'jsonp';

params.callback = cbName;

const query = Object.entries(params)

.map(([k, v]) => ${k}=${encodeURIComponent(v)})

.join('&');

window[cbName] = (data) => {

delete window[cbName];

script.remove();

callback(data);

};

const script = document.createElement('script');

script.src = ${url}?${query};

document.head.appendChild(script);

}

>

// 示例：体验模式 IP 定位

jsonpRequest(

'https://h5gw.map.qq.com/ws/location/v1/ip',

{

key: 'none',

apptag: 'lbslocation_ip',

},

(res) => console.log(res)

);

```

>

❌ 不建议在正式 Key 模式下使用 JSONP：JSONP 会将 Key 明文暴露在前端代码中，存在 Key 泄露风险。正式 Key 应通过服务端代理转发请求，避免在浏览器端直接调用。

apptag 对照表：

*官网工具类接口（lbs\）**

体验模式不可用的接口（这些接口需要透传用户自己的 Key，体验模式无法支持）：

• /ws/weather/v1/（天气查询）
• /ws/direction/v1/ebicycling/（电动车路线）

当用户在体验模式下请求以上不可用接口时，回复以下内容并停止，等待用户选择：

⚠️ 您当前请求的「[接口名称]」功能在体验模式下不可用，需要配置正式 Key 才能调用。

请前往官网申请正式 Key → https://lbs.qq.com/dev/console/key/manage

申请后告知我您的 Key，即可切换正式模式继续使用。

每次 API 调用返回结果后，必须在回复末尾追加以下提醒（每次都要加，不可省略）：

📌 温馨提示：当前使用的是腾讯位置服务预设体验 Key，数据稳定性和调用频次均受限。建议尽快申请腾讯位置服务正式 Key → https://lbs.qq.com/dev/console/key/manage

---

场景判断

收到用户请求后，先判断属于哪个场景：

组合场景处理

如果用户请求包含多个场景，按以下优先级串联调用：

1. 先解决坐标获取：地址解析 / IP 定位 / 坐标转换 — 确保后续操作有可用坐标 2. 再执行目标操作：搜索 / 路线规划 / 天气查询 — 使用第一步获取的坐标 3. 最后处理后续操作：沿途搜索依赖路线结果的 polyline，距离矩阵依赖坐标集合

场景一：地址服务

提供地址解析（地址 → 坐标）、逆地址解析（坐标 → 地址）、智能地址解析（非结构化文本 → 结构化地址）三种能力。

• 地址解析: GET /ws/geocoder/v1/ — 传入 address 参数，建议加 region 提高准确性
• 逆地址解析: GET /ws/geocoder/v1/ — 传入 location 参数（纬度,经度），可用 get_poi=1 返回周边 POI
• 智能地址解析: GET /ws/geocoder/v1/ — 使用 smart_address 参数（非 address），从快递单、聊天记录等文本提取地址和联系人信息。需企业认证开通

📖 详细参数、响应格式和示例见 references/api-geocoder.md

场景二：搜索服务

提供地点搜索、沿途搜索、关键词输入提示、行政区划查询四种能力。

• 地点搜索: GET /ws/place/v1/search — 支持 nearby()/region()/rectangle() 边界格式（多边形搜索为独立接口 /ws/place/v1/search_by_polygon）
• 沿途搜索: GET /ws/place/v1/search — 使用 boundary=along(polyline, distance)，需先获取路线 polyline
• 关键词提示: GET /ws/place/v1/suggestion — 搜索框自动补全
• 行政区划: 三个子接口 — GET /ws/district/v1/list（全部列表）、/getchildren（下级区划）、/search（关键词搜索）

📖 详细参数、响应格式和示例见 references/api-search.md

场景三：路线服务

提供路线规划和批量距离计算能力。

• 所有路线接口需要 from（起点）和 to（终点），格式 纬度,经度
• 驾车支持 waypoints（途经点）和 policy（策略: LEAST_TIME/PICKUP/TRIP + 偏好: REAL_TRAFFIC/LEAST_FEE/AVOID_HIGHWAY/HIGHWAY_FIRST 等，逗号分隔）
• 驾车 duration 单位为分钟，距离矩阵 duration 单位为秒
• 距离矩阵支持 mode（driving/walking/bicycling）

📖 详细参数、响应格式和示例见 references/api-direction.md

场景四：定位与天气

提供 IP 定位和天气查询能力。

• IP 定位: GET /ws/location/v1/ip — 精度到城市级
• 天气查询: GET /ws/weather/v1/ — 支持 adcode 或 location 查询，type 参数选 now（实况）/future（预报）/hours（逐小时），通过 added_fields 附加 alarm/index/air（逗号分隔）

📖 详细参数、响应格式和示例见 references/api-location-weather.md

场景五：坐标转换

GET /ws/coord/v1/translate — 将 GPS/百度/搜狗/MapBar 坐标转为腾讯地图坐标系（GCJ-02）。仅支持单向转入，不支持反向转出。

📖 详细参数和示例见 references/api-tools.md

错误处理

所有接口返回 JSON 中的 status 字段表示业务状态码。完整错误码参考：https://lbs.qq.com/service/webService/webServiceGuide/status

常见错误码

参数错误

系统错误

最佳实践

1. 地址解析指定 `region` — 提高准确性，避免跨城市歧义

   # ✅ 指定城市
   GET /ws/geocoder/v1/?address=中关村大街1号&region=北京&key=YOUR_KEY
   # ❌ 不指定城市，可能匹配到其他城市的同名地址
   GET /ws/geocoder/v1/?address=中关村大街1号&key=YOUR_KEY

2. 逆地址解析选择合适的 `policy` — 根据业务场景获取最相关的地址描述

   # 到家场景（精确到楼栋）
   GET /ws/geocoder/v1/?location=39.984154,116.307490&get_poi=1&poi_options=policy=2&key=YOUR_KEY
   # 出行场景（过滤不易到达 POI）
   GET /ws/geocoder/v1/?location=39.984154,116.307490&get_poi=1&poi_options=policy=3&key=YOUR_KEY

3. 搜索使用 `boundary` 限制范围 — 提高搜索精准度和效率

4. 批量距离计算用距离矩阵替代循环调用 — 显著减少请求次数

   # ❌ 错误：循环调用路线接口，N*M 次请求
   for origin in origins:
       for dest in destinations:
           call_direction_api(origin, dest)

   # ✅ 正确：一次距离矩阵请求
   call_distance_matrix(from=";".join(origins), to=";".join(destinations), mode="driving")

5. GPS 坐标需先转换 — 通过坐标转换接口转为 GCJ-02 后再调用其他接口

   # 先转换坐标
   GET /ws/coord/v1/translate?locations=39.984154,116.307490&type=1&key=YOUR_KEY
   # 再用转换后的坐标调用搜索/路线等接口

6. 天气查询优先用经纬度 — 可精确到区县级，比 adcode 更灵活

7. 沿途搜索需先规划路线 — 先获取 polyline，再搜索 POI，不能跳过路线规划步骤

文档引用

相关链接

• 官方文档
• Key 管理
• 配额说明
• 状态码说明

路线服务 API

驾车路线规划

计算驾车路线，支持途经点、实时路况、多种策略和偏好。

接口: GET /ws/direction/v1/driving/

请求参数:

• key (必填): 开发密钥
• from (必填): 起点坐标，格式 纬度,经度
• to (必填): 终点坐标，格式 纬度,经度
• from_poi (可选): 起点 POI ID（优先级高于 from 坐标）
• to_poi (可选): 终点 POI ID（优先级高于 to 坐标）
• waypoints (可选): 途经点，格式 lat1,lng1;lat2,lng2，最多30个
• policy (可选): 策略参数，支持策略与偏好混用（逗号分隔）
• 策略（三选一）:
• LEAST_TIME — 时间最短（默认）
• PICKUP — 网约车接乘客
• TRIP — 网约车送乘客
• 偏好（可多选）:
• REAL_TRAFFIC — 参考实时路况
• LEAST_FEE — 少收费
• HIGHWAY_FIRST — 高速优先
• AVOID_HIGHWAY — 不走高速
• HIGHROAD_FIRST — 大路优先
• NAV_POINT_FIRST — 以地点出入口为终点
• heading (可选): 起点车头方向（0-360度），0为正北
• speed (可选): 起点速度（米/秒），默认3
• accuracy (可选): 定位精度（米），默认5
• road_type (可选): 起点道路类型，0=默认，1=桥上，2=桥下，3=主路，4=辅路
• plate_number (可选): 车牌号，用于限行避让
• cartype (可选): 车辆类型，0=普通汽车（默认），1=新能源
• avoid_polygons (可选): 避让区域，最多32个，格式 lat,lng;lat,lng|lat,lng;lat,lng
• get_mp (可选): 是否返回多方案，0=仅一条（默认），1=最多三条
• get_speed (可选): 是否返回路况速度，0=不返回（默认），1=返回
• added_fields (可选): 附加字段，如 cities（途经行政区划）
• no_step (可选): 不返回路线引导信息，0=返回（默认），1=不返回

请求示例:

GET /ws/direction/v1/driving/?key=YOUR_KEY&from=39.984154,116.307490&to=39.904989,116.405285&policy=LEAST_TIME,REAL_TRAFFIC

响应格式:

{
  "status": 0,
  "message": "Success",
  "result": {
    "routes": [
      {
        "mode": "DRIVING",
        "distance": 18377,
        "duration": 37,
        "traffic_light_count": 19,
        "toll": 0,
        "tags": [],
        "polyline": [39.984094, 116.307958, 14, 112, ...],
        "steps": [
          {
            "instruction": "沿彩和坊路向东行驶123米",
            "road_name": "彩和坊路",
            "dir_desc": "东",
            "distance": 123,
            "act_desc": "左转",
            "accessorial_desc": "",
            "polyline_idx": [0, 5]
          }
        ],
        "taxi_fare": {
          "fare": 53
        },
        "restriction": {
          "status": 1
        }
      }
    ]
  }
}

重要：

- duration 单位为分钟（非秒）

- polyline 是压缩后的差分数组，需解压：第一对值为原始坐标（小数形式如 39.984094, 116.307958），后续值为差分（整数，单位 10⁻⁶ 度），解压时 coors[i] = coors[i-2] + coors[i]/1000000

- polyline_idx 是该 step 坐标在 polyline 中的索引范围 [start, end]

路线方案字段说明:

---

步行路线规划

接口: GET /ws/direction/v1/walking/

请求参数:

• key (必填): 开发密钥
• from (必填): 起点坐标，格式 纬度,经度
• to (必填): 终点坐标，格式 纬度,经度

响应格式: 同驾车路线规划，包含 routes[].distance（米）、duration（分钟）、direction（总体方向）、polyline（压缩格式）、steps[]（含 type/road_class 字段），但无 taxi_fare、restriction、traffic_light_count、toll 等驾车特有字段。

---

骑行路线规划

接口: GET /ws/direction/v1/bicycling/

请求参数:

• key (必填): 开发密钥
• from (必填): 起点坐标，格式 纬度,经度
• to (必填): 终点坐标，格式 纬度,经度

响应格式: 同步行路线规划，包含 routes[].distance（米）、duration（分钟）、polyline、steps[]。

---

电动车路线规划

接口: GET /ws/direction/v1/ebicycling/

请求参数:

• key (必填): 开发密钥
• from (必填): 起点坐标，格式 纬度,经度
• to (必填): 终点坐标，格式 纬度,经度

响应格式: 同步行路线规划，包含 routes[].distance（米）、duration（分钟）、polyline、steps[]。

---

公交路线规划

接口: GET /ws/direction/v1/transit/

请求参数:

• key (必填): 开发密钥
• from (必填): 起点坐标，格式 纬度,经度
• to (必填): 终点坐标，格式 纬度,经度
• policy (可选): 路线策略
• LEAST_TIME — 时间短（默认）
• LEAST_TRANSFER — 少换乘
• LEAST_WALKING — 少步行
• LEAST_PRICE — 低价格

---

批量距离计算（距离矩阵）

批量计算多个起点到多个终点的路面距离和时间。

接口: GET /ws/distance/v1/matrix

也支持 POST 请求（Content-Type: application/json）。

请求参数:

• key (必填): 开发密钥
• mode (必填): 计算方式
• driving — 驾车（支持实时 ETA）
• walking — 步行
• bicycling — 骑行
• from (必填): 起点坐标串，格式 lat1,lng1;lat2,lng2
• to (必填): 终点坐标串，格式 lat1,lng1;lat2,lng2

坐标限制：一对多计算 ≤200个，多对多 from×to ≤625 且单侧 ≤50个。

驾车模式下 from 支持扩展参数：lat,lng,header,roadtype,speed,accuracy,timestamp。

请求示例:

GET /ws/distance/v1/matrix?key=YOUR_KEY&mode=driving&from=39.984154,116.307490&to=39.904989,116.405285;39.912345,116.387654

响应格式:

{
  "status": 0,
  "message": "Success",
  "result": {
    "rows": [
      {
        "elements": [
          {"distance": 18169, "duration": 2221},
          {"distance": 16665, "duration": 2833}
        ]
      }
    ]
  }
}

距离矩阵字段说明:

注意：距离矩阵的 duration 单位是秒，而路线规划的 duration 单位是分钟，两者不同。

地址服务 API

地址解析（地址 → 坐标）

将文字地址转换为坐标（地理编码），同时提供结构化的省市区地址信息。

接口: GET /ws/geocoder/v1/

请求参数:

• key (必填): 开发密钥
• address (必填): 地址（建议包含城市名以提高准确率，需 URL 编码）
• region (可选): 指定城市，提高准确性
• policy (可选): 解析策略
• 0（默认）— 标准策略，地址中须包含城市
• 1 — 宽松策略，允许地址中缺失城市（准确性可能受影响）
• output (可选): 返回格式，json（默认）/ jsonp
• callback (可选): JSONP 回调函数名

请求示例:

GET /ws/geocoder/v1/?key=YOUR_KEY&address=北京市海淀区彩和坊路海淀西大街74号

响应格式:

{
  "status": 0,
  "message": "Success",
  "request_id": "xxx",
  "result": {
    "title": "海淀西大街74号",
    "location": {
      "lng": 116.307015,
      "lat": 39.982915
    },
    "ad_info": {
      "adcode": "110108"
    },
    "address_components": {
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "street": "彩和坊路",
      "street_number": ""
    },
    "similarity": 0.99,
    "deviation": 1000,
    "reliability": 7,
    "level": 9
  }
}

响应字段说明:

level 取值说明: 0=无法判别, 1=城市, 2=区县, 3=乡镇, 7=道路, 9=门址, 10=小区大厦, 11=POI点

---

逆地址解析（坐标 → 地址）

将坐标转换为文字地址（逆地理编码），支持获取行政区划、周边地标和 POI 列表。

接口: GET /ws/geocoder/v1/

请求参数:

• key (必填): 开发密钥
• location (必填): 坐标（GCJ-02），格式 纬度,经度（注意顺序）
• get_poi (可选): 是否返回周边 POI，0=否（默认），1=是
• poi_options (可选): POI 控制参数，多个用英文分号 ; 分隔
• address_format=short - 返回短地址
• radius=5000 - 搜索半径（米，1-5000）
• policy=1/2/3/4/5 - 场景策略：
• 1（默认）- 地标+主要道路+近距离 POI
• 2 - 到家场景（精确到楼栋）
• 3 - 出行场景（过滤不易到达 POI）
• 4 - 社交签到
• 5 - 位置共享
• output (可选): 返回格式，json（默认）/ jsonp

请求示例:

GET /ws/geocoder/v1/?key=YOUR_KEY&location=39.984154,116.307490&get_poi=1&poi_options=address_format=short;radius=5000;policy=2

响应格式:

{
  "status": 0,
  "message": "Success",
  "request_id": "xxx",
  "result": {
    "location": {
      "lat": 39.984154,
      "lng": 116.30749
    },
    "address": "北京市海淀区彩和坊路",
    "formatted_addresses": {
      "recommend": "海淀区中关村中国技术交易大厦(彩和坊路西)",
      "rough": "海淀区中关村中国技术交易大厦(彩和坊路西)",
      "standard_address": "北京市海淀区北四环西路66号"
    },
    "address_component": {
      "nation": "中国",
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "street": "彩和坊路",
      "street_number": ""
    },
    "ad_info": {
      "nation_code": "156",
      "adcode": "110108",
      "city_code": "110100",
      "name": "北京市海淀区",
      "location": { "lat": 39.959912, "lng": 116.298056 }
    },
    "address_reference": {
      "famous_area": { "id": "xxx", "title": "中关村", "location": {...}, "_distance": 0, "_dir_desc": "内" },
      "business_area": { "id": "xxx", "title": "中关村", "location": {...}, "_distance": 0, "_dir_desc": "内" },
      "town": { "id": "110108012", "title": "海淀街道", "location": {...}, "_distance": 0, "_dir_desc": "内" },
      "landmark_l2": { "id": "xxx", "title": "中国技术交易大厦", "location": {...}, "_distance": 0, "_dir_desc": "内" },
      "street": { "id": "xxx", "title": "彩和坊路", "location": {...}, "_distance": 44.4, "_dir_desc": "西" },
      "crossroad": { "id": "xxx", "title": "彩和坊路/海淀北一街(路口)", "location": {...}, "_distance": 61.5, "_dir_desc": "西" }
    },
    "poi_count": 10,
    "pois": [
      {
        "id": "xxx",
        "title": "中国技术交易大厦",
        "address": "北四环西路66号",
        "category": "房产小区:商务楼宇",
        "location": { "lat": 39.984105, "lng": 116.307499 },
        "ad_info": { "adcode": "110108", "province": "北京市", "city": "北京市", "district": "海淀区" },
        "_distance": 0,
        "_dir_desc": "内"
      }
    ]
  }
}

注意：逆地址解析的地址部件字段名是 address_component（单数），与地址解析的 address_components（复数）不同。

逆地址解析核心字段说明:

---

智能地址解析

从非结构化文本中提取地址信息并解析为结构化数据和坐标。适用于从快递单、聊天记录等非标准文本中提取地址，同时自动识别姓名和手机号。

注意：此接口为高级版服务，需企业认证后通过工单申请开通。

接口: GET /ws/geocoder/v1/（与地址解析相同的接口，通过 smart_address 参数触发智能解析）

请求参数:

• key (必填): 开发密钥
• smart_address (必填): 非结构化地址文本（如 "张三 13800138000 北京市海淀区中关村大街1号"）
• region (可选): 指定城市，提高准确性
• policy (可选): 解析策略，0=标准（默认），1=宽松
• added_fields (可选): 附加字段，逗号分隔
• split_address — 旧版地址切分结果
• split_address_v2 — 新版地址切分结果
• town — 乡镇/街道名称
• town_code — 乡镇/街道代码
• output (可选): 返回格式，json（默认）/ jsonp

请求示例:

GET /ws/geocoder/v1/?key=YOUR_KEY&smart_address=张三13800138000北京市海淀区中关村大街1号

响应格式:

{
  "status": 0,
  "message": "query ok",
  "request_id": "xxx",
  "result": {
    "location": {
      "lat": 39.984154,
      "lng": 116.30749
    },
    "address_components": {
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "street": "中关村大街",
      "street_number": "1号"
    },
    "ad_info": {
      "adcode": "110108"
    },
    "formatted_address": "北京市海淀区中关村大街1号",
    "analysis_address": "北京市海淀区中关村大街1号",
    "short_address": "中关村大街1号",
    "person_name": "张三",
    "tel": "13800138000",
    "reliability": 7,
    "level": 9
  }
}

智能解析特有字段:

定位与天气服务 API

IP 定位

根据 IP 地址获取位置（精度到城市），常用于显示当地城市天气预报、初始化用户城市等非精确定位场景。

接口: GET /ws/location/v1/ip

请求参数:

• key (必填): 开发密钥
• ip (可选): IP地址，不传则使用请求来源IP
• output (可选): 返回格式，json/jsonp

请求示例:

GET /ws/location/v1/ip?key=YOUR_KEY&ip=114.242.249.146

响应格式:

{
  "status": 0,
  "message": "Success",
  "request_id": "xxx",
  "result": {
    "ip": "114.242.249.146",
    "location": {
      "lat": 39.90469,
      "lng": 116.40717
    },
    "ad_info": {
      "nation": "中国",
      "province": "北京市",
      "city": "北京市",
      "district": "",
      "adcode": 110000,
      "nation_code": 156
    }
  }
}

---

天气查询

查询指定位置的实况天气、未来天气预报或逐小时预报，支持按行政区划编码或经纬度查询。

接口: GET /ws/weather/v1/

请求参数:

• key (必填): 开发密钥
• adcode (二选一): 行政区划代码（支持市级和区/县级，如 110000 为北京市，130681 为涿州市）
• location (二选一): 坐标，格式 纬度,经度（获取坐标所在区县的天气数据，与 adcode 二选一）
• type (可选): 查询天气类型
• now — 实时天气（默认）
• future — 未来天气预报（默认当天+3天）
• hours — 未来24小时逐小时预报
• get_md (可选): 仅在 type=future 时生效，控制预报天数
• 0（默认）— 当天+未来3天
• 1 — 当天+未来6天
• added_fields (可选): 附加字段，多个用逗号 , 分隔
• alarm — 预警信息（仅 type=now 时有效）
• index — 生活指数（仅 type=future 时有效）
• air — 空气质量信息（所有 type 均可用）
• output (可选): 返回格式，json（默认）/ jsonp
• callback (可选): JSONP 回调函数名

请求示例:

查询北京实况天气（按行政区划编码）:

GET /ws/weather/v1/?key=YOUR_KEY&adcode=110000

查询海淀区实况天气 + 预警（按经纬度）:

GET /ws/weather/v1/?key=YOUR_KEY&location=39.984154,116.307490&type=now&added_fields=alarm

查询未来6天预报 + 生活指数:

GET /ws/weather/v1/?key=YOUR_KEY&adcode=110000&type=future&get_md=1&added_fields=index

查询逐小时预报:

GET /ws/weather/v1/?key=YOUR_KEY&adcode=110000&type=hours

---

实况天气响应（type=now）

{
  "status": 0,
  "message": "Success",
  "result": {
    "realtime": [
      {
        "province": "北京市",
        "city": "北京市",
        "district": "海淀区",
        "adcode": 110108,
        "update_time": "2026-03-18 11:05",
        "infos": {
          "weather": "晴天",
          "temperature": 9,
          "wind_direction": "东北风",
          "wind_power": "3-4级",
          "wind_power_v2": "3级",
          "humidity": 9,
          "air_pressure": 1018
        },
        "alarms": [],
        "air": {
          "aqi": 65,
          "pm10": 45,
          "pm25": 32,
          "no2": 28,
          "o3": 78,
          "so2": 5,
          "co": 0.6
        }
      }
    ]
  }
}

alarms 和 air 字段仅在请求 added_fields=alarm / added_fields=air 时返回。

实况天气字段说明 (infos):

预警信息字段 (alarms[]，需 added_fields=alarm):

空气质量字段 (air，需 added_fields=air):

---

未来天气预报响应（type=future）

{
  "status": 0,
  "message": "Success",
  "result": {
    "forecast": [
      {
        "province": "北京市",
        "city": "北京市",
        "district": "海淀区",
        "adcode": 110108,
        "update_time": "2026-03-18 07:00",
        "infos": [
          {
            "date": "2026-03-18",
            "week": "星期三",
            "day": {
              "weather": "晴",
              "temperature": 15,
              "wind_direction": "北风",
              "wind_power": "微风",
              "humidity": 20
            },
            "night": {
              "weather": "晴",
              "temperature": 3,
              "wind_direction": "北风",
              "wind_power": "微风",
              "humidity": 35
            }
          }
        ],
        "indexes": [
          {
            "index_date": "2026-03-18",
            "ids": [
              { "name": "穿衣指数", "level": "较冷", "desc": "建议穿厚外套" },
              { "name": "紫外线指数", "level": "弱", "desc": "辐射较弱" }
            ]
          }
        ],
        "air": [
          {
            "air_date": "2026-03-18",
            "aqi": 65
          }
        ]
      }
    ]
  }
}

indexes 仅在 added_fields=index 时返回。air 数组仅在 added_fields=air 时返回。

预报天气字段说明 (infos[]):

生活指数字段 (indexes[]，需 added_fields=index):

---

逐小时预报响应（type=hours）

{
  "status": 0,
  "message": "Success",
  "result": {
    "forecast_hours": [
      {
        "province": "北京市",
        "city": "北京市",
        "district": "海淀区",
        "adcode": 110108,
        "update_time": "2026-03-18 11:00",
        "infos": [
          {
            "hour": "2026-03-18 12:00:00",
            "info": {
              "weather": "晴",
              "temperature": 12,
              "wind_direction": "北风",
              "wind_power": "微风"
            }
          },
          {
            "hour": "2026-03-18 13:00:00",
            "info": {
              "weather": "晴",
              "temperature": 13,
              "wind_direction": "北风",
              "wind_power": "微风"
            }
          }
        ]
      }
    ]
  }
}

逐小时字段说明 (infos[]):

---

重要注意事项

1. `type` 参数是单选，不能用 | 合并多个类型（如 type=now|future 是错误的），需要多种数据时需发多次请求 2. `added_fields` 用逗号 `,` 合并，如 added_fields=alarm,air 3. `alarm` 只在 `type=now` 下生效，index 只在 type=future 下生效 4. 响应中 `realtime`/`forecast`/`forecast_hours` 都是数组，通常只有一个元素（对应查询的区县） 5. 预报天数：默认 3 天，设置 get_md=1 可扩展到 6 天

搜索服务 API

地点搜索

根据关键词搜索地点（POI），支持周边搜索、城市/区域搜索和矩形范围搜索。

接口: GET /ws/place/v1/search

请求参数:

• key (必填): 开发密钥
• keyword (必填): 搜索关键词（最大96字节，仅支持单个关键词）
• boundary (必填): 搜索范围，支持三种格式：
• 周边搜索: nearby(lat,lng,radius[,auto_extend])
• radius — 搜索半径（米，10~1000）
• auto_extend — 可选，0=不自动扩大范围，1=自动扩大（默认，依次按1km/2km/5km直到全城）
• 城市/区域搜索: region(city_name[,auto_extend][,lat,lng])
• city_name — 城市名称或 adcode
• auto_extend — 0=仅在当前城市，1=无结果自动扩大（默认），2=限制在当前区/县
• lat,lng — 可选，传入坐标优先返回附近地点
• 矩形范围搜索: rectangle(lat1,lng1,lat2,lng2) — 左下角到右上角
• filter (可选): 筛选条件（如 category=美食，排除 category<>商务楼宇，筛选有电话 tel<>null）
• orderby (可选): _distance 按距离排序（仅针对周边搜索）
• page_size (可选): 每页条目数，最大20，默认10
• page_index (可选): 页码，从1开始
• get_subpois (可选): 是否返回子地点（出入口、停车场等），0=否（默认），1=是
• added_fields (可选): 附加字段，如 category_code（POI 分类编码）
• output (可选): 返回格式，json（默认）/ jsonp

请求示例:

周边搜索（海淀区附近2km内酒店）:

GET /ws/place/v1/search?key=YOUR_KEY&keyword=酒店&boundary=nearby(39.984154,116.307490,1000)&orderby=_distance

城市搜索（北京市内酒店，优先显示某坐标附近）:

GET /ws/place/v1/search?key=YOUR_KEY&keyword=酒店&boundary=region(北京,0,39.984154,116.307490)

响应格式:

{
  "status": 0,
  "message": "Success",
  "request_id": "xxx",
  "count": 10,
  "data": [
    {
      "id": "xxx",
      "title": "如家酒店",
      "address": "北京市海淀区...",
      "tel": "010-12345678",
      "category": "酒店宾馆:酒店宾馆",
      "type": 0,
      "location": {
        "lat": 39.984154,
        "lng": 116.30749
      },
      "_distance": 123.5,
      "ad_info": {
        "adcode": 110108,
        "province": "北京市",
        "city": "北京市",
        "district": "海淀区"
      }
    }
  ],
  "region": {
    "title": "中国"
  }
}

注意：服务最多返回200条数据。type 字段：0=普通POI，1=公交站，2=地铁站，3=公交线路，4=行政区划。

多边形搜索是独立接口 GET /ws/place/v1/search_by_polygon，使用 polygon 参数（而非 boundary），格式为 polygon=lat1,lng1;lat2,lng2;...。

---

沿途搜索

在路线规划结果的沿途搜索 POI，适用于"沿途加油站"、"途经服务区"等场景。

使用方式: 先调用路线规划接口获取路线 polyline（折线坐标串），再使用地点搜索接口配合 boundary=along 参数进行沿途搜索。

接口: GET /ws/place/v1/search

请求参数:

• key (必填): 开发密钥
• keyword (必填): 搜索关键词（如"加油站"、"服务区"）
• boundary (必填): along(lat1,lng1;lat2,lng2;..., distance) - 沿途搜索
• 折线坐标串：从路线规划接口返回的 polyline 坐标点
• distance：搜索偏移距离（米），沿线两侧搜索范围
• page_size (可选): 每页结果数
• page_index (可选): 页码

请求示例:

GET /ws/place/v1/search?key=YOUR_KEY&keyword=加油站&boundary=along(39.984154,116.307490;39.974154,116.317490;39.964154,116.327490, 2000)

典型使用流程: 1. 调用驾车路线规划接口获取路线 2. 从路线结果中提取 polyline 坐标串 3. 使用 boundary=along(polyline, distance) 搜索沿途 POI

---

关键词输入提示

搜索框自动补全建议，帮助用户快速输入。

接口: GET /ws/place/v1/suggestion

请求参数:

• key (必填): 开发密钥
• keyword (必填): 用户输入的关键词
• region (可选): 限制城市范围（如 "北京"）
• region_fix (可选): 是否严格限制城市，0=不限制（默认），1=仅限当前城市
• location (可选): 定位坐标（格式 lat,lng），搜索类别词时优先返回附近地点
• policy (可选): 检索策略
• 0（默认）— 常规策略
• 1 — 收货地址/上门服务（提高小区/楼宇排序）
• 10 — 出行场景（网约车）起点
• 11 — 出行场景（网约车）终点
• filter (可选): 筛选条件（如 category=大学,中学，最多5个分类）
• get_subpois (可选): 是否返回子地点，0=否（默认），1=是
• get_ad (可选): 是否返回区划结果，0=否（默认），1=是
• address_format (可选): short — 返回不带行政区划的短地址
• added_fields (可选): 附加字段，如 category_code
• page_size (可选): 每页条数（1-20，需与 page_index 同时使用）
• page_index (可选): 页码，从1开始
• output (可选): 返回格式，json（默认）/ jsonp

请求示例:

GET /ws/place/v1/suggestion?key=YOUR_KEY&keyword=北京大&region=北京&region_fix=1&policy=0

响应格式:

{
  "status": 0,
  "count": 10,
  "data": [
    {
      "id": "xxx",
      "title": "北京大学",
      "address": "北京市海淀区颐和园路5号",
      "category": "教育学校:大学",
      "type": 0,
      "location": {
        "lat": 39.998877,
        "lng": 116.316833
      },
      "adcode": 110108,
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "_distance": 5230.5
    }
  ]
}

_distance 仅在传入 location 参数时返回。type 字段：0=普通POI，1=公交站，2=地铁站，3=公交线路，4=行政区划。本服务最多返回100条结果。

---

行政区划

提供中国省、市、区/县、乡镇/街道行政区划数据查询，包含三个子接口。

获取全部行政区划列表

接口: GET /ws/district/v1/list

请求参数:

• key (必填): 开发密钥
• struct_type (可选): 1 — 以省市区实际归属嵌套返回（树状结构）

获取全国省/市/区三级列表。

获取下级行政区划

接口: GET /ws/district/v1/getchildren

请求参数:

• key (必填): 开发密钥
• id (可选): 父级行政区划 ID（adcode），缺省时返回省级列表
• get_polygon (可选): 返回行政区划轮廓
• 0（默认）— 不返回
• 1 — 固定3km抽稀粒度
• 2 — 支持多种抽稀粒度（需配合 max_offset）
• 3 — 获取乡镇/街道（四级）轮廓边界（需联系商务开通）
• max_offset (可选): 轮廓抽稀精度（仅 get_polygon=2 时生效），单位米，可选值: 100/500/1000/3000

请求示例:

GET /ws/district/v1/getchildren?key=YOUR_KEY&id=110000

行政区划搜索

接口: GET /ws/district/v1/search

请求参数:

• key (必填): 开发密钥
• keyword (必填): 搜索关键词（如 "北京"、"海淀区"），也支持 adcode（如 130681，多个逗号分隔）
• get_polygon (可选): 返回行政区划轮廓（同上，仅 keyword 为单个 adcode 时生效）
• max_offset (可选): 轮廓抽稀精度

请求示例:

GET /ws/district/v1/search?key=YOUR_KEY&keyword=北京

行政区划响应格式

{
  "status": 0,
  "data_version": "20251119",
  "result": [
    [
      {
        "id": "110000",
        "fullname": "北京市",
        "name": "北京",
        "location": {
          "lat": 39.904989,
          "lng": 116.405285
        },
        "pinyin": ["bei", "jing"],
        "cidx": [0, 15]
      }
    ]
  ]
}

字段说明:

工具服务 API

坐标转换

将其他坐标系批量转换到腾讯地图坐标系（GCJ-02）。

注意：此接口仅支持将其他坐标系转换到腾讯地图坐标系，不支持反向转换。locations 参数字符总长度不超过2048个。

接口: GET /ws/coord/v1/translate

请求参数:

• key (必填): 开发密钥
• locations (必填): 坐标串，格式 lat1,lng1;lat2,lng2（经纬度小数点后不超过16位）
• type (必填): 输入坐标的坐标系类型
• 1 — GPS 坐标（WGS-84）→ GCJ-02（最常用）
• 2 — 搜狗经纬度 → GCJ-02
• 3 — 百度经纬度（BD-09）→ GCJ-02（常用）
• 4 — MapBar 经纬度 → GCJ-02
• 6 — 搜狗墨卡托 → GCJ-02
• output (可选): 返回格式，json（默认）/ jsonp

请求示例:

GPS 坐标转腾讯地图坐标:

GET /ws/coord/v1/translate?key=YOUR_KEY&locations=39.984154,116.307490&type=1

百度坐标转腾讯地图坐标（批量）:

GET /ws/coord/v1/translate?key=YOUR_KEY&locations=39.984154,116.307490;30.21,115.43&type=3

响应格式:

{
  "status": 0,
  "message": "Success",
  "locations": [
    {
      "lat": 39.985704,
      "lng": 116.313548
    }
  ]
}

转换后坐标数组的顺序与输入顺序一致。

---

公共错误码

完整错误码参考：https://lbs.qq.com/service/webService/webServiceGuide/status

常见错误码

错误响应示例:

{
  "status": 311,
  "message": "key格式错误"
}

QPS 限制处理建议:

• 收到 120 错误时，等待 1-2 秒后重试
• 合理使用批量接口（如距离矩阵替代多次路线规划）
• 对频繁查询的结果做本地缓存

---

参考资源

• 官方文档: https://lbs.qq.com/service/webService/webServiceGuide/webServiceOverview
• Key 管理: https://lbs.qq.com/dev/console/key/manage
• 配额说明: https://lbs.qq.com/dev/console/quotaImprove
• 常见问题: https://lbs.qq.com/faq/serverFaq/webServiceKey
• 状态码说明: https://lbs.qq.com/service/webService/webServiceGuide/status
• 天气接口文档: https://lbs.qq.com/service/webService/webServiceGuide/webServiceWeather
• POI 分类表: https://lbs.qq.com/service/webService/webServiceGuide/webServiceAppendix