引入腾讯地图定位SDK文档

官方API接口地址

官方首页

官方定位SDK使用说明

官方定位SDK参考手册

官方定位SDK资源下载

引入步骤

申请Key

1. 登录腾讯位置服务

登录方式支持：QQ、微信、手机。

2. 验证手机与邮箱

验证手机与邮箱申请成为开发者，同时也可以进行企业认证，获取更多服务。
成为企业用户。
个人开发者免费调用量1万/天，并发量5次/秒。（下表为个人开发者配额表）

接口	免费额度与用量（次/日）	并发配额（次/秒）	接口解释
坐标转换	1w	5	实现从其它地图供应商坐标系或标准GPS坐标系，批量转换到腾讯地图坐标系
逆地址解析(位置描述)	1w	5	本接口提供由坐标到坐标所在位置的文字描述的转换。输入坐标返回地理位置信息和附近poi列表
地址解析	1w	5	本接口提供由地址描述到所述位置坐标的转换，与逆地址解析的过程正好相反
IP定位	1w	5	通过终端设备IP地址获取其当前所在地理位置，精确到市级，常用于显示当地城市天气预报、初始化用户城市等非精确定位场景

企业开发者免费调用量30万/天，并发量50次/秒，企业开发者还可以付费购买配额（配额价格只有企业开发者才可以查询）。

3. 申请开发密钥（key）

成为开发者之后，在控制台的key管理中就可以申请创建新密钥。

导入库文件

库文件下载地址

找到开发包中的 libtencentloc.zip文件夹，拷贝相应目录下的so文件到目标工程中的 libs目录下。

找到开发包中的 TencentLocationSDK_v4.3.0_r196568.jar 文件，拷贝到目标工程中的 libs 目录下。

注意：如果 TencentLocationSDK_v4.3.0_r196568.jar没有自动加入到工程的 build path 中，则需要手动添加。手动添加的步骤如下：右击工程，在工程属性->Java Build Path->Libraries中选择“Add External JARs”，选定 TencentLocationSDK_v4.3.0_r196568.jar，确定后返回。这样您就可以在程序中使用腾讯地图定位SDK了。

配置权限

配置Key

...

添加混淆

-keepclassmembers class  ** {
    public  void  on*Event(...);
}
-keep class  c.t.**{*;}
-keep class  com.tencent.map.geolocation.**{*;}
-keep class  com.tencent.tencentmap.lbssdk.service.**{*;}

-dontwarn  org.eclipse.jdt.annotation.**
-dontwarn  c.t.**

功能说明

创建位置监听器

TencentLocationListener，这是一个接口，需要实现一下方法：

位置更新回调

public void onLocationChanged(TencentLocation location, int error, String reason)

参数	含义
location	新的位置
error	错误码
reason	错误描述

GPS和WIFI状态回调
```
public void onStatusUpdate(String name, int status, String desc)
```
参数含义

name GPS，Wi-Fi等

status 新的状态, 启用或禁用

desc 状态描述

在Android 6.0 及以上的系统版本中，当位置开关关闭时，onStatusUpdate接口会返回name=wifi，status=5，该状态码说明位置开关关闭，此时无法进行Wi-Fi扫描。收到该状态码后，请及时提醒用户打开位置开关。

参数	含义
name	GPS，Wi-Fi等
status	新的状态, 启用或禁用
desc	状态描述

Name	status
	状态	状态码	说明
cell	STATUS_DISABLED	0	模块关闭
	STATUS_EABLED	1	模块开启
	STATUS_DENIED	2	定位权限被禁止，位置权限被拒绝通常发生在禁用当前应用的 ACCESS_COARSE_LOCATION 等定位权限
wifi	STATUS_DISABLED	0	Wi-Fi开关关闭
	STATUS_EABLED	1	Wi-Fi开关打开
	STATUS_DENIED	2	权限被禁止，禁用当前应用的 ACCESS_COARSE_LOCATION 等定位权限
	STATUS_LOCATION_SWITCH_OFF	5	位置信息开关关闭，在android M系统中，此时禁止进行Wi-Fi扫描
GPS	STATUS_DISABLED	0	GPS开关关闭
	STATUS_EABLED	1	GPS开关打开
	STATUS_GPS_AVAILABEL	3	GPS可用，代表GPS开关打开，且搜星定位成功
	STATUS_GPS_UNAVAILABLE	4	GPS不可用，不可用有多种可能，比如： GPS开关被关闭，GPS开关开着但是没办法搜星或者在室内等定位不成功的情况

创建定位请求

TencentLocationRequest 类代表定位请求，您的APP通过向定位SDK发送定位请求来启动定位。通常您只需获取 TencentLocationRequest 实例即可，如下所示：

TencentLocationRequest request = TencentLocationRequest.create()

以上得到的是一个缺省的定位请求，缺省的定位请求各参数如下：

定位周期(位置监听器回调周期): 10秒
Request Level: REQUEST_LEVEL_NAME
缓存: 允许使用缓存
QQ: 空字符串

可调用如下方法来对定位请求进行自定义配置：

方法名	功能
setInterval	设置定位周期(位置监听器回调周期), 单位为 ms (毫秒)
setRequestLevel	设置定位的 request level
setAllowCache	设置是否允许使用缓存, 连续多次定位时建议允许缓存
setQQ	设置 QQ 号

Request level 决定定位结果中包含哪些信息，分为以下几类：

Request Level	值	含义
REQ_LEVEL_GEO	0	包含经纬度 ,例：经度:40.050486,纬度:116.298929
REQ_LEVEL_NAME	1	包含经纬度, 位置名称, 位置地址
REQ_LEVEL_ADMIN_AREA	3	包含经纬度，位置所处的中国大陆行政区划
REQ_LEVEL_POI	4	包含经纬度，位置所处的中国大陆行政区划及周边POI列表

注册位置监听器

TencentLocationManager 类代表腾讯定位服务。注册位置监听器前需要获取 TencentLocationManager 实例，示例如下：

Context context = ...
TencentLocationListener listener = ...
TencentLocationRequest request = ...
TencentLocationManager locationManager = TencentLocationManager.getInstance(context);
int error = locationManager.requestLocationUpdates(request, listener);

返回值为0时表示位置监听器注册成功。注册成功之后，在位置发生变化时，位置监听器的位置回调接口或状态回调接口将会被调用，用以接收最新的位置或状态。

返回值非0时表示位置监听器注册失败。注册监听器失败时，将无法接收到位置更新，继续使用腾讯地图定位SDK前您应先排查注册失败的问题。常见的返回值如下：

返回值	含义
0	注册位置监听器成功
1	设备缺少使用腾讯定位SDK需要的基本条件
2	配置的 Key 不正确
3	自动加载libtencentloc.so失败，可能由以下原因造成： 1、这往往是由工程中的so与设备不兼容造成的，应该添加相应版本so文件; 2、如果您使用AndroidStudio,可能是gradle没有正确指向so文件加载位置，可以按照这里配置您的gradle;

获取定位结果

通过位置监听器的位置回调接口获取定位结果。使用定位结果前应当先检查错误码：

@Override
public void onLocationChanged(TencentLocation location, int error, String reason) {
    if (TencentLocation.ERROR_OK == error) {
        // 定位成功
    } else {
        // 定位失败
    }
}

错误码说明

错误码来自 TencentLocation 的 ERROR_XXX 常量，分如下几种情形：

错误码	值	含义
ERROR_OK	0	定位成功
ERROR_NETWORK	1	网络问题引起的定位失败
ERROR_BAD_JSON	2	GPS, Wi-Fi 或基站错误引起的定位失败： 1、用户的手机确实采集不到定位凭据，比如偏远地区比如地下车库电梯内等; 2、开关跟权限问题，比如用户关闭了位置信息，关闭了Wi-Fi，未授予app定位权限等。
ERROR_WGS84	4	无法将WGS84坐标转换成GCJ-02坐标时的定位失败
ERROR_UNKNOWN	404	未知原因引起的定位失败

request level 说明

request level 来自 TencentLocationRequest 的 REQUEST_LEVEL_XXX 常量，分如下几种情形：

Request Level	值	含义
REQ_LEVEL_GEO	0	包含经纬度
REQ_LEVEL_NAME	1	包含经纬度, 位置名称, 位置地址
REQ_LEVEL_ADMIN_AREA	3	包含经纬度，位置所处的中国大陆行政区划
REQ_LEVEL_POI	4	包含经纬度，位置所处的中国大陆行政区划及周边POI列表

当定位请求的 request level 为 REQ_LEVEL_GEO 时，以下字段有效:
精度：通常精度为：GPS：<20米，WiFi：30-180米，基站：150-800米.

字段	含义	例
latitude	纬度	40.050486
longitude	经度	116.299057
altitude	海拔	0.0
accuracy	精度	30.0

当定位请求的 request level 为 REQ_LEVEL_NAME 时，以下字段有效:

字段	含义	例
latitude	纬度	40.050486
longitude	经度	116.299057
altitude	海拔	0.0
accuracy	精度	30.0
name	名称	上地科技大厦
address	地址	北京市海淀区上地西街8

当定位请求的 request level 为 REQ_LEVEL_ADMIN_AREA 时，以下字段有效:

字段	含义	例
latitude	纬度	40.050486
longitude	经度	116.299057
altitude	海拔	0.0
accuracy	精度	30.0
nation	国家	中国
province	省	北京市
city	市	北京市
district	区	海淀区
town	镇	Unknown
village	村	Unknown
street	街道	上地西路
streetNo	门号	上地西街8号

当定位请求的 request level 为 REQ_LEVEL_POI 时，以下字段有效:

字段	含义	例
latitude	纬度	40.050486
longitude	经度	116.299057
altitude	海拔	0.0
accuracy	精度	30.0
nation	国家	中国
province	省	北京市
city	市	北京市
district	区	海淀区
town	镇	Unknown
village	村	Unknown
street	街道	上地西路
streetNo	门号	上地西街8号
poiList	POI 列表

删除位置监听器

定位完成后，无论成功或失败，都应当尽快删除之前注册的位置监听器。代码如下：

Context context = ...
TencentLocationListener listener = ...
TencentLocationManager locationManager =
                        TencentLocationManager.getInstance(context);
locationManager.removeUpdates(listener);

Android 6.0说明

Android 6.0系统在原有的AndroidManifest.xml声明权限的基础上新增了运行时权限动态检测，定位等权限也包含在其中。如果您的应用程序设置了 targetSdkVersion ≥ 23，则需要在调用定位功能前进行权限检查，权限检查的示例代码如下：

if (Build.VERSION.SDK_INT >= 23) {
     String[] permissions = {
                Manifest.permission.ACCESS_COARSE_LOCATION,
                Manifest.permission.READ_PHONE_STATE,
                Manifest.permission.WRITE_EXTERNAL_STORAGE
        };

if (checkSelfPermission(permissions[0]) != PackageManager.PERMISSION_GRANTED)
{
    requestPermissions(permissions, 0);
}
    }

用户选择允许或拒绝后，会回调onRequestPermissionsResult方法:

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    //可在此继续其他操作。
}

常见问题

无法定位成功

首先请检查您的程序编写正确。可使用我们提供的 Demo 进行对比验证。
请确保是在真机上运行程序。
请确保网络连接可用，即3G或WiFi正常(不要求必须开启GPS)。可使用不同的网络环境进行对比验证。
请确定您的 Key 是否正确。
受限于基站和WiFi热点分布范围及更新速度，无法 100% 保证网络定位成功。建议将设备移动到 500~800 米外重新测试。

如果仍然无法定位成功，请到反馈建议平台中查看类似问题或直接提问，会有专人为您解答。

是否免费? 调用有次数限制吗？

目前腾讯定位SDK完全免费，且没有单日调用上限的限制。

什么是腾讯手机地图定位SDK?

腾讯地图定位SDK是一套基于Android 2.1及以上版本设备的应用程序接口，通过该接口，您可以轻松的使用腾讯地图定位服务，构建LBS应用程序。

定位SDK包括GPS定位与网络定位，实现了经纬度坐标偏转与当前位置的POI名称、地址或者行政区划的查询。采用了移动缓存策略，节省流量与电量。

安卓引入腾讯地图定位SDK文档