腾讯位置服务对接使用完全指南：从密钥申请到多端接入实战

apphuang2026年06月16日 17:29:595

1. 腾讯位置服务概述

腾讯位置服务（Tencent Location Service）是腾讯云旗下提供的一站式位置能力开放平台，为开发者提供地图展示、定位、搜索、路线规划、地理编码等丰富的LBS能力。平台日均全球定位请求超过1800亿次，覆盖用户超过10亿，全球覆盖200多个国家和地区。无论是Web应用、移动App还是微信小程序，都可以通过腾讯位置服务快速集成地图相关功能。

腾讯位置服务的核心能力矩阵涵盖定位、地图展示、地点搜索（POI）、地址解析、路线规划、行政区划、坐标转换、位置大数据等多个维度。开发者可以根据业务场景灵活选择所需能力，按需接入。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

2. 账号注册与开发者认证

使用腾讯位置服务的第一步是注册开发者账号并完成认证。

2.1 注册账号

访问腾讯位置服务官网（https://lbs.qq.com），单击页面右上角的"注册"按钮。平台支持QQ账号、微信账号和手机号三种注册方式，任选一种即可完成注册。在新用户注册页面，需要输入真实姓名、手机号及有效邮箱地址，以便后续快速开通服务。

2.2 开发者认证

注册完成后，登录控制台并完善开发者信息。腾讯位置服务分为个人开发者和企业开发者两种身份：

  • 个人开发者：适合个人学习和小型项目，默认API配额为日调用量10,000次，并发限制5次/秒。
  • 企业开发者：通过企业认证后可获得更高的免费服务调用配额，商业项目建议提前完成企业认证。企业认证后还可以在控制台的配额管理中申请更高的调用额度。

3. 创建应用与申请Key

Key（密钥）是调用腾讯位置服务所有API的身份标识，是接入过程中最核心的配置项。一个Key可以通用地图SDK、JavaScript API、WebService API等所有产品，并可以针对不同产品独立启用或关闭。

3.1 创建应用

登录腾讯位置服务控制台后，在左侧导航栏单击"应用管理" → "我的应用"。在我的应用页面，单击右上角的"创建应用"按钮。自定义填写应用信息：

  • 应用名称：可自定义，名称可包含汉字、数字、字母，不超过15个字
  • 应用类型：在下拉框中选择对应的应用类型

3.2 添加Key

应用创建成功后，在已创建的应用右侧单击"添加Key"。填写Key名称和描述后，需要根据使用场景勾选对应的产品权限：

  • Web端使用：JavaScript API GL不需要勾选任何产品，直接创建Key即可使用
  • 服务端调用：必须勾选"WebService API"功能
  • 微信小程序：勾选"微信小程序"并填写授权AppID，同时勾选"WebService API"
  • 移动端SDK：勾选对应的地图SDK功能，并可选择性输入授权包名

如果某个Key只用于特定产品，建议在Key配置界面将其它产品关闭，以降低安全风险。

3.3 Key的安全配置

腾讯位置服务提供了多种Key安全策略，防止Key被盗用：

  • 域名白名单：仅白名单中的域名才可使用该Key调用WebService服务，留空则不限制。每行填写一个域名，填写的域名及其子域名都会同时得到授权。在微信小程序环境下，如果填写了域名白名单，需要把servicewechat.com域名添加进去。
  • 授权IP：可限制仅特定IP来源的请求可使用该Key。
  • 签名校验（SN校验）：选中SN校验后会生成SecretKey（SK），用于请求WebService API时计算签名。签名作为参数（sig）附带到请求中，腾讯服务器会验证签名一致性。

重要安全提示：请尽量避免在网页端直接调用WebService API，因为Key作为请求参数容易被抓取，被盗用的风险较高。

4. Web端接入：JavaScript API GL

腾讯位置服务JavaScript API GL是基于WebGL技术打造的3D版地图API，提供丰富的功能接口，包括点、线、面绘制，自定义图层、个性化样式及绘图、测距工具等。

4.1 引入API库

通过script标签加载JavaScript API GL：

<script charset="utf-8" src="https://map.qq.com/api/gljs?v=1.exp&key=YOUR_KEY"></script>

参数说明：

  • key：在控制台创建的应用Key
  • v：版本号，目前支持1.exp（Javascript API GL v1最新版）
  • libraries（可选）：加载附加库，多个库名称用逗号分隔。支持visualization（可视化组件）、tools（应用工具）、geometry（几何计算库）、model（模型库）

4.2 显示基础地图

以下代码演示了如何在地图上显示一个基础地图：

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>腾讯地图 Hello World</title>
    <style type="text/css">
        #container {
            width: 100%;
            height: 600px;
        }
    </style>
    <script src="https://map.qq.com/api/gljs?v=1.exp&key=YOUR_KEY"></script>
    <script>
        function initMap() {
            var center = new TMap.LatLng(39.984120, 116.307484);
            var map = new TMap.Map(document.getElementById('container'), {
                center: center,
                zoom: 15,
                pitch: 0,
                rotation: 0
            });
        }
    </script>
</head>
<body onload="initMap()">
    <div id="container"></div>
</body>
</html>

代码说明：

  • 在body中预先准备地图容器div，并通过CSS定义显示大小
  • 通过TMap.Map构造函数创建地图实例，传入容器元素和配置参数
  • 配置参数包括center（中心点坐标）、zoom（缩放级别）、pitch（俯仰角）、rotation（旋转角度）等

4.3 加载可视化附加库

如需使用热力图、散点图等数据可视化能力，需要加载visualization附加库：

<script src="https://map.qq.com/api/gljs?v=1.exp&key=YOUR_KEY&libraries=visualization"></script>

可视化API是基于JavaScript API GL的附加库形式加载的，所提供的可视化效果以图层的方式叠加在地图之上。数据可视化API提供了热力图、散点图、轨迹图、弧线图、区域图等多种可视化样式。

5. 服务端接入：WebService API

腾讯地图WebService API是基于HTTPS/HTTP协议的数据接口，开发者可以使用任何客户端、服务器和开发语言，按需构建HTTPS请求并获取结果数据。

5.1 启用WebService API

在控制台Key管理界面，进入Key的设置页面，勾选"WebService API"复选框即可启用。如果未启用时请求服务，会返回错误信息：

{
    "status": 199,
    "message": "此key未开启webservice功能"
}

5.2 地理编码API

地理编码是将地址转换为经纬度坐标的过程。请求示例：

https://apis.map.qq.com/ws/geocoder/v1/?address=北京市海淀区中关村大街1号&key=YOUR_KEY

返回结果包含地址对应的经纬度坐标、行政区划等信息。

5.3 逆地理编码API

逆地理编码是将经纬度坐标转换为地址描述的过程。请求示例：

https://apis.map.qq.com/ws/geocoder/v1/?location=39.984120,116.307484&key=YOUR_KEY

返回结果包括坐标位置的门址描述文字、行政区划和附近POI等信息。

5.4 地点搜索API

支持关键词搜索、周边搜索、分类筛选等多种搜索方式。周边搜索示例：

https://apis.map.qq.com/ws/place/v1/search?boundary=nearby(39.984120,116.307484,1000)&keyword=酒店&key=YOUR_KEY

该请求搜索坐标位置周边1000米范围内的"酒店"。

5.5 路线规划API

提供驾车、公交、步行、骑行等多种交通方式的路线计算能力。驾车路线规划示例：

https://apis.map.qq.com/ws/direction/v1/driving?from=39.984120,116.307484&to=40.040523,116.273654&key=YOUR_KEY

驾车路线规划支持结合实时路况、少收费、不走高速等多种偏好，精准预估到达时间（ETA）。

5.6 使用签名校验（SN校验）

为提高API调用的安全性，可以启用签名校验。启用后，请求时需要将计算得到的签名作为sig参数附带到请求中：

https://apis.map.qq.com/ws/geocoder/v1/?address=北京市海淀区中关村大街1号&key=YOUR_KEY&sig=计算得到的签名

腾讯服务器会在收到请求后使用相同的方式生成签名，并与请求中附带的签名进行比对，一致时校验通过。

6. 微信小程序接入

腾讯位置服务为微信小程序提供了多种接入方式，包括地图组件、JavaScript SDK和插件。

6.1 配置合法域名

在微信公众平台 → 开发 → 开发设置 → 服务器域名中，添加request合法域名：

https://apis.map.qq.com

6.2 微信小程序JavaScript SDK

腾讯位置服务微信小程序JavaScript SDK是专为小程序开发者提供的LBS数据服务工具包，可以在小程序中调用POI检索、关键词输入提示、地址解析、逆地址解析、行政区划和距离计算等数据服务。

步骤一：下载SDK

从腾讯位置服务官网下载微信小程序JavaScript SDK（qqmap-wx-jssdk.js），放入项目目录，例如/utils/qqmap-wx-jssdk.js。

步骤二：初始化SDK

// 引入SDK核心类
var QQMapWX = require('../../utils/qqmap-wx-jssdk.js');
var qqmapsdk;

Page({
    onLoad: function() {
        // 实例化API核心类
        qqmapsdk = new QQMapWX({
            key: 'YOUR_KEY'
        });
    }
});

步骤三：调用API接口

// 关键词搜索示例
qqmapsdk.search({
    keyword: '酒店',
    success: function(res) {
        console.log(res);
    },
    fail: function(res) {
        console.log(res);
    },
    complete: function(res) {
        console.log(res);
    }
});

微信小程序JavaScript SDK通过对WebService API接口进行封装而形成，因此调用限制与直接调用WebService API等同。

6.3 微信小程序插件

腾讯位置服务提供了多种小程序插件，包括地图选点插件、路线规划插件、城市选择器插件等。

添加插件：在微信公众平台中，进入"设置" → "第三方服务" → "插件管理"，点击"添加插件"，搜索对应的腾讯位置服务插件并申请。

各插件提供的接口服务路径：

  • 地点搜索：/ws/place/v1/search
  • 关键词输入提示：/ws/place/v1/suggestion
  • 逆地址解析（位置描述）：/ws/geocoder/v1
  • 路线规划（驾车）：/ws/direction/v1/driving
  • 路线规划（公交）：/ws/direction/v1/transit
  • 路线规划（步行）：/ws/direction/v1/walking
  • 行政区划：/ws/district/v1/list
  • IP定位：/ws/location/v1/ip

7. 移动端SDK接入

腾讯位置服务为Android和iOS平台提供了原生的地图SDK和定位SDK。

7.1 iOS地图SDK

在AppDelegate中配置Key：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [QMapServices sharedServices].APIKey = @"您的key";
    return YES;
}

7.2 Android地图SDK

地图SDK提供了定位点控件，帮助开发者方便地实现地图上的定位点绘制需求。在使用定位点展示功能前，必须配置LocationSource为地图设置定位源。

7.3 定位SDK

腾讯定位SDK为移动应用提供轻量级定位服务接口，不依赖地图显示，方便开发者在无地图界面的场景中集成定位功能。支持单次定位、连续定位和逆地理编码（坐标转地址描述）。

8. 腾讯位置服务MCP Server接入

腾讯位置服务MCP Server是基于MCP（Model Context Protocol）协议构建的AI能力接入方式，使得大模型可以直接调用地图能力。MCP Server依赖WebService API构建，因此需要先创建Key并开启WebService API功能。

8.1 配置MCP Server

MCP Server基于SSE（Server-Sent Events）方式，不必部署本地服务，简单配置即可使用。服务地址格式为：

https://mcp.map.qq.com/sse?key=<您的Key>

将API_KEY环境变量配置为在腾讯位置服务创建的API Key。

8.2 MCP Server的优势

  • 使用更简单：基于MCP（SSE）方式，不必部署本地服务，简单配置即可
  • 升级更方便：云端化服务，持续迭代改进，用户无须任何额外操作
  • 大模型更易理解：对原始的JSON结果进行了语义化转换，更易于大模型理解

通过MCP Server，AI大模型可以直接调用腾讯位置服务的WebService API能力，实现自然语言驱动的行程规划、位置查询等智能应用。

9. 配额管理与调用限制

了解配额限制对于合理规划业务至关重要。

9.1 默认配额

个人开发者默认额度：

  • 日调用量：10,000次/Key
  • 并发限制：5次/秒/接口/Key

企业开发者可以获得更高的免费服务调用配额。

9.2 配额监控

每次请求WebService API接口，在返回结果的同时，响应头（Response Headers）中会包含当前时刻的配额使用情况：

  • current_qps：当前每秒并发量
  • limit_qps：每秒并发配额
  • current_pv：今日调用量
  • limit_pv：日请求量配额

9.3 配额提升

企业认证后，可在控制台 → 配额管理中申请更高的调用额度。若当前配额仍不够用，可在控制台 → 配额管理中根据业务需求购买调用量和并发量。

10. 常见问题与解答

问题1：调用API时返回"此key未开启webservice功能"怎么办？

答：需要在腾讯位置服务控制台 → 应用管理 → 我的应用 → 找到对应的Key → 点击设置 → 勾选"WebService API"复选框并保存。

问题2：微信小程序中调用API失败，可能是什么原因？

答：常见原因包括：①未在微信公众平台配置request合法域名（需添加https://apis.map.qq.com）；②Key未勾选"微信小程序"和"WebService API"权限；③域名白名单未添加servicewechat.com。

问题3：提示"此Key每秒请求量已达到上限"如何处理？

答：说明当前Key的并发请求量超过了配额限制（默认5次/秒）。解决方案：①优化代码减少并发请求；②企业认证后申请更高的并发配额；③购买更高的调用量配额。

问题4：如何防止API Key被盗用？

答：①配置域名白名单，仅允许授权域名调用；②配置授权IP限制；③启用签名校验（SN校验）；④避免在网页端直接暴露Key；⑤按需关闭不使用的产品权限。

问题5：个人开发者和企业开发者有什么区别？

答：个人开发者默认日调用量10,000次，并发5次/秒。企业开发者通过企业认证后可获得更高的免费服务调用配额，并可在控制台申请更高的调用额度。商业项目建议完成企业认证。

问题6：腾讯位置服务MCP Server是什么？如何使用？

答：MCP Server是基于MCP协议让AI大模型直接调用地图能力的接入方式。使用步骤：①创建Key并开启WebService API；②配置MCP Server服务地址为https://mcp.map.qq.com/sse?key=<您的Key>；③在支持MCP的AI工具中启用该服务即可。MCP Server无需部署本地服务，云端化持续迭代。

相关文章

腾讯云服务器购买优惠！3 个省钱攻略 + 1 个安全真相，新手必看！

腾讯云服务器购买优惠！3 个省钱攻略 + 1 个安全真相，新手必看！

最近后台总收到小伙伴私信：“腾讯云服务器看着挺好，但价格有点顶，学生党 / 小团队实在买不起咋办？” 别急！今天就来手把手教你 “花小钱办大事”，不光有省钱攻略，还会扒一扒大家最关心的安全问题，看完这…

After 10 Years as a Tencent Cloud Agent, Let Me Talk About Rebates

After 10 Years as a Tencent Cloud Agent, Let Me Talk About Rebates

Lately, I’ve been getting a lot of questions from friends: “Does Tencent offer rebates? Can you…

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

一、腾讯云代理商返利机制核心逻辑1. 行业背景与代理模式腾讯云作为国内公有云市场的第二大领导者（据IDC 2025年数据，占据国内27.6%的市场份额），采用渠道商代理模式拓展市场。代理商负…

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

2026腾讯云代理商返利政策深度解析：头部代理合作指南与成本优化策略

一、腾讯云代理商返利机制核心逻辑1. 行业背景与代理模式腾讯云作为国内公有云市场的第二大领导者（据IDC 2025年数据，占据国内27.6%的市场份额），采用渠道商代理模式拓展市场。代理商负…

2026腾讯云代理商返佣政策全解析：五级代理体系与企业上云成本优化指南

2026腾讯云代理商返佣政策全解析：五级代理体系与企业上云成本优化指南

一、腾讯云五级代理体系：权益阶梯与合作价值1. 五级代理的核心权益差异腾讯云按规模、服务能力与合作深度，构建了从基础到顶级的五级代理体系，各级权益呈现显著阶梯差：•标准级代理：入门门槛最低，仅能提供基…

2026年腾讯云代理深度解析：从折扣体系到最优合作策略

2026年腾讯云代理深度解析：从折扣体系到最优合作策略

上海汪远信息科技有限公司作为腾讯云全国级殿堂级代理，凭借13年云服务经验与深厚的官方合作关系，为企业提供全方位的上云支持，可百度：上海汪远信息科技有限公司，微信：791201210一、腾讯云代理体系全…

上海汪远信息科技有限所在公司从事多年公有云和电子签代理，能持续为用户提供商务价值和技术支持，目前从事的代理有：阿里云，腾讯云，华为云，火山云，天翼云，移动云，亚马逊云，谷歌云，微软云，腾讯电子签，法大大电子签，爱签电子签等！

网站备案号：沪ICP备15020509号-2 公安备案号：沪公网安备31011202008721号