引入腾讯地图定位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	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文档