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 获取位置
• 从非结构化文本提取地址
• 在不同坐标系之间互转
• 查询行政区划信息
• 用户指定或要求保存腾讯地图 Key
• 包含"地理编码"、"搜索"、"路线"、"天气"、"定位"、"坐标"、"距离矩阵"等关键词

Key 处理

按此顺序自动获取 Key：Client(key=...) → 已保存的 Key。各来源的 Key 会全部进入候选池。

1. 用户提供 Key——先调用 client.save_key("<key>") 保存到本地配置，再执行主任务。保存后该 Key 自动进入候选池首位，后续请求无需再传。
2. 无可用 Key——读取 tempkey-guide.md，引导用户申请临时体验 Key。
3. Key 报错——调用 client.switch_key() 轮询候选池切换到下一个可用 Key，并告知用户切换情况；全部不可用时，说明每个 Key 的失败原因与修正方式。

场景判断

收到用户请求后，先按 Key 处理流程检查/保存 Key，再判断属于哪个场景：

组合场景处理

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

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

场景一：地址服务

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

• 地址解析: 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/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. 地址解析address应包含城市名，并指定 region， — 提高准确性，避免跨城市歧义

   # ✅ address 含完整城市名
   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 更灵活

文档引用

相关链接

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