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

apphuang2026年07月15日 11:31:3357

1. 腾讯位置服务概述

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

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

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

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

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

2.1 注册账号

访问腾讯位置服务官网，单击页面右上角的"注册"按钮。平台支持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
  • Android/iOS：需勾选对应SDK并填写包名

创建完Key后还需要分配调用配额：在右侧菜单选择配额管理 → 账户额度，点击一键分配，系统会自动把地点搜索、路线规划、逆地址解析等接口的配额分配给你的Key。

4. Web端接入：JavaScript API GL

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

4.1 加载API库

通过引入script标签加载API服务：

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

其中参数说明：

  • key：在控制台 → 应用管理 → 我的应用界面创建得到的Key
  • v：代表引用的版本号，目前仅支持1.exp
  • libraries：用来指明加载的附加库，支持visualization（可视化组件库）、tools（应用工具）、geometry（几何计算库）、model（模型库）

4.2 初始化地图

下面演示利用JavaScript API GL实现地图显示：

<!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: 500px;
        }
    </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: 30,
                rotation: 0
            });
        }
    </script>
</head>
<body onload="initMap()">
    <div id="container"></div>
</body>
</html>

关键步骤说明：

  1. 在body中预先准备地图容器，并在CSS样式中定义地图显示大小
  2. 引入API库
  3. 创建并显示地图的代码（本例中通过页面onload事件触发运行init函数）

4.3 添加标记与交互

// 创建标记
var marker = new TMap.MultiMarker({
    map: map,
    styles: {
        'default': new TMap.MarkerStyle({
            'width': 30,
            'height': 30,
            'anchor': { x: 15, y: 30 }
        })
    },
    geometries: [{
        id: 'marker_1',
        styleId: 'default',
        position: new TMap.LatLng(39.984120, 116.307484)
    }]
});

// 添加信息窗口
var infoWindow = new TMap.InfoWindow({
    map: map,
    position: new TMap.LatLng(39.984120, 116.307484),
    content: '<div>这里是北京</div>'
});
infoWindow.open();

5. 服务端接入：WebService API

腾讯地图WebService API是基于HTTPS/HTTP协议构建的标准化地理数据服务接口。开发者可以使用任何客户端、服务器端技术及编程语言，遵循API规范发起HTTPS请求，获取地理信息服务（目前支持JSON/JSONP格式的数据返回）。

5.1 启用服务

在Key配置界面勾选WebService复选框，即为启用该产品。未启用时请求服务会返回：

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

5.2 地点搜索

以下示例为搜索坐标位置周边1000米范围内的"酒店"：

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

5.3 地址解析（正向地理编码）

将地址转换为经纬度坐标：

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

5.4 逆地址解析

将经纬度坐标转换为地址描述：

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

5.5 路线规划

支持驾车、步行、骑行、公交等多种交通方式：

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

5.6 Java后端调用示例

在实际项目中，建议将API调用放在后端，前端调用自己的后端接口，然后后端再去调用腾讯的API。这种架构不仅解决了跨域问题，还能更好地保护API Key不被暴露。

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class TencentMapService {
    private static final String KEY = "YOUR_KEY";
    private static final String BASE_URL = "https://apis.map.qq.com/ws/geocoder/v1/";

    public static String geocode(String address) throws Exception {
        String urlStr = BASE_URL + "?address=" + java.net.URLEncoder.encode(address, "UTF-8") + "&key=" + KEY;
        URL url = new URL(urlStr);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setConnectTimeout(5000);
        conn.setReadTimeout(5000);

        BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"));
        StringBuilder result = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            result.append(line);
        }
        reader.close();
        conn.disconnect();
        return result.toString();
    }

    public static String reverseGeocode(double lat, double lng) throws Exception {
        String urlStr = BASE_URL + "?location=" + lat + "," + lng + "&key=" + KEY;
        // 同上发起HTTP请求
        return "";
    }
}

注意：腾讯地图API要求纬度在前，经度在后。建议将Key存储在环境变量或配置中心，不要直接硬编码在代码中。

6. 微信小程序接入

腾讯位置服务为微信小程序提供了专属的JavaScript SDK，可以直接在小程序中调用POI检索、地址解析、逆地址解析等服务。

6.1 配置合法域名

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

  • request合法域名：https://apis.map.qq.com

6.2 下载并引入SDK

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

6.3 初始化SDK

在需要使用地图服务的页面，引入并初始化：

// 引入SDK核心类
var QQMapWX = require('../../utils/qqmap-wx-jssdk.js');
var qqmapsdk = new QQMapWX({
    key: 'YOUR_KEY'  // 替换为你申请的Key
});

6.4 逆地址解析示例

// 使用逆地址解析获取位置描述
qqmapsdk.reverseGeocoder({
    location: {
        latitude: 39.984120,
        longitude: 116.307484
    },
    success: function(res) {
        console.log(res.result.address);
        console.log(res.result.formatted_addresses.recommend);
    },
    fail: function(err) {
        console.error(err);
    }
});

6.5 地点搜索示例

// 关键词搜索
qqmapsdk.search({
    keyword: '火锅',
    boundary: 'nearby(39.984120,116.307484,1000)',
    success: function(res) {
        console.log(res.data);
    },
    fail: function(err) {
        console.error(err);
    }
});

7. 移动端SDK接入

7.1 Android SDK

Android地图SDK提供了定位点控件，帮助开发者方便地实现地图上的定位点绘制需求。

集成步骤：

  1. 在build.gradle中添加依赖
  2. 在AndroidManifest.xml中添加权限配置
  3. 在AndroidManifest.xml的application节点下添加TencentMapSDK元数据配置，值为申请的Key
  4. 在代码中初始化地图
// 在Activity中初始化地图
TencentMap tencentMap = mapView.getMap();
// 设置定位源
Location location = new Location("LongPressLocationProvider");
tencentMap.setLocationSource(location);
// 显示定位点
tencentMap.setMyLocationEnabled(true);

7.2 iOS SDK

腾讯地图iOS SDK目前提供了Objective-C版本的SDK。Swift项目需要通过Bridging文件来引入。

集成步骤：

  1. 将TencentLBS.framework拷贝到工程目录
  2. 在Xcode的Target中选择"Build Phases" → "Link Binary With Libraries"添加框架
  3. 在AppDelegate中配置Key
// Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [QMapServices sharedServices].APIKey = @"您的key";
    return YES;
}

7.3 Flutter插件

腾讯位置服务已发布官方Flutter插件，定位SDK与地图SDK已完成Flutter适配。开发者只需编写一套Dart代码，即可在Android与iOS双端直接调用原生级能力。

// 在pubspec.yaml中添加依赖
dependencies:
  tencent_location_flutter_plugin: ^latest_version

// 在代码中使用
import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';

TencentLocationFlutterPlugin tencentLocation = TencentLocationFlutterPlugin();
tencentLocation.init(key: "YOUR_KEY");
tencentLocation.startContinuousLocation();

8. 配额管理与额度分配

8.1 配额说明

腾讯位置服务的调用配额按开发者身份有所不同：

  • 个人开发者：日调用量10,000次，并发限制5次/秒
  • 企业开发者：可获得更高的免费服务调用配额
  • 商业授权开发者：初始额度更高，如需更高额度可付费提额

8.2 配额分配

创建Key之后，需要在控制台 → 配额管理 → 账户额度中进行额度分配。点击"一键分配"，系统自动将各接口的调用配额分配给Key。

8.3 实时监控

每次请求WebServiceAPI接口，在返回结果的同时，响应头中会包含这一时刻的配额使用情况：

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

9. Key安全策略

腾讯位置服务的调用配额是开放到Key上的，为防止Key被盗用，保障调用安全，Key的设置中提供了多种安全策略：

9.1 产品权限独立开关

同一个Key可以用在地图SDK、JavaScript API、WebService API等各产品中，可针对不同产品独立启用或关闭。假设某个Key只会调用地图SDK，可在Key配置界面将其它产品关闭，以降低安全风险。

9.2 域名白名单

WebService API支持设置域名白名单，只有白名单内的域名才能使用该Key发起请求。

9.3 包名绑定

Android和iOS SDK支持绑定包名（Bundle ID），只有对应包名的应用才可使用该Key。

9.4 避免前端直接调用

请尽量避免在网页端直接调用WebServiceAPI，因Key作为请求参数容易被抓取到，被盗用的风险较高。建议将API调用放在后端服务中。

10. 跨域问题解决方案

腾讯的WebServiceAPI不支持跨域，必须采用后端代理方案。把API调用放在后端，前端调用自己的后端接口，然后后端再去调用腾讯的API。这种架构不仅解决了跨域问题，还能更好地保护API Key不被暴露。

10.1 限流处理

腾讯地图API有QPS限制，解决方案是实现请求队列+限流机制：

class RateLimiter {
    constructor(qps) {
        this.queue = [];
        this.processing = false;
        this.interval = 1000 / qps;
        this.lastRun = 0;
    }

    add(task) {
        return new Promise((resolve, reject) => {
            this.queue.push({ task, resolve, reject });
            this.process();
        });
    }

    async process() {
        if (this.processing || this.queue.length === 0) return;
        this.processing = true;
        const now = Date.now();
        const wait = Math.max(0, this.interval - (now - this.lastRun));
        if (wait > 0) await new Promise(r => setTimeout(r, wait));
        const { task, resolve, reject } = this.queue.shift();
        this.lastRun = Date.now();
        try {
            const result = await task();
            resolve(result);
        } catch (err) {
            reject(err);
        }
        this.processing = false;
        this.process();
    }
}

// 使用示例
const limiter = new RateLimiter(5);
limiter.add(() => fetch('https://apis.map.qq.com/ws/place/v1/search?keyword=火锅&key=YOUR_KEY'));

11. 常见问题与排查

11.1 常见错误码

  • status: 199：此Key未开启WebService功能。解决方案：在控制台Key配置中勾选WebService API
  • status: 302：Key非法或配额超限。解决方案：检查Key是否正确，查看配额是否用完
  • status: 310：请求参数错误。解决方案：检查请求参数格式是否正确
  • status: 121：每日调用量已达到上限。解决方案：申请更高配额或等待次日重置

11.2 小程序定位失败常见原因

  • 用户未授权"地理位置"权限：需在小程序wx.getSetting后调用wx.openSetting引导开启
  • 手机系统级定位服务关闭
  • 微信客户端版本过低（建议v8.0.30+）
  • 小程序未配置合法域名（qqmap-wx-jssdk.min.js必须在request合法域名单中）
  • 网络环境差导致API请求超时

11.3 验证Key是否可用

直接在浏览器地址栏输入以下URL，如果返回JSON数据说明配置成功：

https://apis.map.qq.com/ws/place/v1/search?keyword=火锅&boundary=region(成都,0)&key=你申请的Key

12. 总结

腾讯位置服务提供了从Web到移动端、从服务端到小程序的完整接入方案。本文从账号注册、Key申请、权限配置入手，详细介绍了JavaScript API GL、WebService API、微信小程序SDK、Android/iOS SDK以及Flutter插件的接入方法，并涵盖了配额管理、安全策略、跨域处理和常见问题排查等关键内容。

接入的核心要点可以概括为：

  1. 注册开发者账号并完成认证，商业项目建议完成企业认证以获得更高配额
  2. 创建应用并申请Key，根据使用场景勾选对应的产品权限
  3. 分配调用配额，确保Key有足够的调用额度
  4. 根据平台选择对应的接入方式，Web端用JavaScript API GL，服务端用WebService API，小程序用JavaScript SDK，移动端用原生SDK
  5. 注意Key安全，避免在前端直接暴露Key，使用后端代理调用WebService API

掌握以上要点，即可快速完成腾讯位置服务的对接与集成。

常见问题解答

问1：腾讯位置服务的Key在哪里申请？

答：登录腾讯位置服务控制台（https://lbs.qq.com），在左侧导航栏单击"应用管理" → "我的应用"，创建应用后添加Key即可获取。

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

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

问3：JavaScript API GL和WebService API有什么区别？

答：JavaScript API GL是Web端的地图展示和交互API，用于在浏览器中渲染地图、添加标记等；WebService API是服务端HTTP接口，用于地点搜索、地址解析、路线规划等数据查询，不支持跨域直接调用。

问4：微信小程序接入腾讯位置服务需要配置什么？

答：需要在微信公众平台配置request合法域名（https://apis.map.qq.com），下载qqmap-wx-jssdk.js并引入项目，在代码中初始化SDK并传入Key。

问5：调用WebService API返回status:199是什么原因？

答：表示该Key未开启WebService功能。需要在控制台 → 应用管理 → 我的应用中，找到对应的Key并勾选"WebService API"权限。

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

答：建议采取以下措施：①避免在前端直接调用WebService API，将API调用放在后端服务中；②在Key配置中设置域名白名单；③Android/iOS SDK绑定包名；④对不使用的产品权限及时关闭。

相关文章

腾讯云服务器购买优惠！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号