tencentmap-webservice-skill

name: tencentmap-webservice-skill description: '腾讯位置服务 WebService API 开发技能。当开发者需要通过 HTTP 接口集成地理编码、地点搜索、路线规划、天气查询、IP 定位等位置服务时，此技能提供完整的 API 调用指导。适用场景：(1) 地址与坐标互转 (2) 地点搜索与周边 POI 查询 (3) 关键词输入提示与自动补全 (4) 沿途搜索 (5) 路线规划（驾车/步行/骑行/电动车/公交）(6) 距离矩阵与批量距离计算 (7) IP 定位 (8) 天气查询 (9) 智能地址解析 (10) 坐标系转换 (11) 行政区划查询。不包含地图渲染和前端可视化，仅提供 HTTP JSON 数据接口。当用户提到地理编码、地址转坐标、逆地址解析、POI 搜索、路线规划、距离矩阵、批量距离、天气查询、IP 定位、坐标转换、行政区划、输入提示、自动补全、WebService API 时触发。⚠️ 强制行为：本 Skill 加载后，第一个动作必须是检查是否存在正式 Key（环境变量 TMAP_WEBSERVICE_KEY 或用户已在对话中提供）。若已有正式 Key，直接继续处理用户请求。若没有正式 Key，必须立即向用户展示 Key 选择提示（正式 Key 注册引导 + 预设体验 Key 选项），然后停止等待用户选择，不得在用户选择之前进行任何分析、读取文件、规划方案或编写代码的操作。' description_zh: "腾讯位置服务 WebService API（地理编码、搜索、路线、天气、定位）" description_en: "Tencent Maps WebService API for geocoding, search, routing, weather & location" version: 1.0.0 homepage: https://lbs.qq.com/service/webService/webServiceGuide/webServiceOverview allowed-tools: Read,Glob,Grep metadata: clawdbot: emoji: "🗺️" requires: env: - TMAP_WEBSERVICE_KEY

腾讯位置服务 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 回调。

// ✅ 体验模式：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 管理
• 配额说明
• 状态码说明