腾讯位置服务 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 或对话中用户已提供）

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

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

1. 情况 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=函数名 参数，通过动态插入