引入高德定位SDK文档

官方API接口地址

官方首页

官方定位SDK使用说明

官方定位SDK参考手册

官方定位SDK资源下载

引入步骤

申请Key

1. 登录高德位置服务

登录方式支持：账户、手机号、淘宝、支付宝、微博和QQ。

2. 验证手机与邮箱

验证手机与邮箱申请成为开发者，同时也可以进行企业认证，获取更多服务。

成为个人开发和成为企业开发者。

3. 申请开发密钥（key）

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

使用

1. 导入库文件

​ 库文件下载地址

将下载的定位 SDK jar 文件复制到工程的 libs 目录下，如果有老版本定位 jar 文件存在，请删除。

2.配置 build.gradle 文件

在 build.gradle 文件的 dependencies 中配置 compile fileTree(include: ['*.jar'], dir: 'libs')。

3. 配置AndroidManifest.xml

1. 声明Service组件

<service android:name="com.amap.api.location.APSService"></service>

2. 声明权限

Android 6.0及以上系统可以参考Android 6.0权限说明章节。

1. <!--用于进行网络定位-->
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
   <!--用于访问GPS定位-->
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
   <!--用于获取运营商信息，用于支持提供运营商信息相关的接口-->
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
   <!--用于访问wifi网络信息，wifi信息会用于进行网络定位-->
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
   <!--用于获取wifi的获取权限，wifi信息会用来进行网络定位-->
   <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
   <!--用于访问网络，网络定位需要上网-->
   <uses-permission android:name="android.permission.INTERNET"></uses-permission>
   <!--用于读取手机当前的状态-->
   <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
   <!--用于写入缓存数据到扩展存储卡-->
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
   <!--用于申请调用A-GPS模块-->
   <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"></uses-permission>
   <!--用于申请获取蓝牙信息进行室内定位-->
   <uses-permission android:name="android.permission.BLUETOOTH"></uses-permission>
   <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"></uses-permission>
   

2. 设置高德Key

<meta-data android:name="com.amap.api.v2.apikey" android:value="key">//开发者申请的key               
</meta-data>

获取我的Key。

4.初始化定位

在主线程中声明AMapLocationClient类对象，需要传Context类型的参数。推荐用getApplicationContext()方法获取全进程有效的context。

//声明AMapLocationClient类对象
public AMapLocationClient mLocationClient = null;
//初始化定位
mLocationClient = new AMapLocationClient(getApplicationContext());

5.配置参数并启动定位

1. 创建AMapLocationClientOption对象

//声明AMapLocationClientOption对象
public AMapLocationClientOption mLocationOption = null;
//初始化AMapLocationClientOption对象
mLocationOption = new AMapLocationClientOption();

AMapLocationClientOption核心方法解析:

下表是设置定位参数的核心方法，是以下配置参数代码段中方法的详细展开。

2. 选择定位场景

   说明：该部分功能从定位SDK v3.7.0开始提供。如果开发者选择了对应的定位场景，那么则不用自行设置AMapLocationClientOption中的其他参数，SDK会根据选择的场景自行定制option参数的值，当然开发者也可以在基础上进行自行设置。实际按最后一次设置的参数值生效。

   目前支持3种定位场景的设置：签到、出行、运动。默认无场景。

/**
     * 设置定位场景，目前支持三种场景（签到、出行、运动，默认无场景）
     */
    mLocationOption.setLocationPurpose(AMapLocationClientOption.AMapLocationPurpose.SignIn);
    if(null != locationClient){
      mLocationClient.setLocationOption(option);
      //设置场景模式后最好调用一次stop，再调用start以保证场景模式生效
      mLocationClient.stopLocation();
      mLocationClient.startLocation();
    }

AMapLocationClientOption.AMapLocationPurpos 定位场景常量如下：

3. 选择定位模式

高德定位服务包含GPS和网络定位（Wi-Fi和基站定位）两种能力。定位SDK将GPS、网络定位能力进行了封装，以三种定位模式对外开放，SDK默认选择使用高精度定位模式。

高精度定位模式：会同时使用网络定位和GPS定位，优先返回最高精度的定位结果，以及对应的地址描述信息。

//设置定位模式为AMapLocationMode.Hight_Accuracy，高精度模式。
mLocationOption.setLocationMode(AMapLocationMode.Hight_Accuracy);

​ 低功耗定位模式：不会使用GPS和其他传感器，只会使用网络定位（Wi-Fi和基站定位）；

//设置定位模式为AMapLocationMode.Battery_Saving，低功耗模式。
mLocationOption.setLocationMode(AMapLocationMode.Battery_Saving);

​ 仅用设备定位模式：不需要连接网络，只使用GPS进行定位，这种模式下不支持室内环境的定位，需要在室外环境下才可以成功定位。注意，自 v2.9.0 版本之后，仅设备定位模式下支持返回地址描述信息。

//设置定位模式为AMapLocationMode.Device_Sensors，仅设备模式。
mLocationOption.setLocationMode(AMapLocationMode.Device_Sensors);

4. 配置定位次数

   1. 设置单次定位

      如果您需要使用单次定位，需要进行如下设置：

   //获取一次定位结果：
   //该方法默认为false。
   mLocationOption.setOnceLocation(true);
   
   //获取最近3s内精度最高的一次定位结果：
   //设置setOnceLocationLatest(boolean b)接口为true，启动定位时SDK会返回最近3s内精度最高的一次定位结果。如果设置其为true，setOnceLocation(boolean b)接口也会被设置为true，反之不会，默认为false。
   mLocationOption.setOnceLocationLatest(true);
   
   

   2. 自定义连续定位

   SDK默认采用连续定位模式，时间间隔2000ms。如果您需要自定义调用间隔：

   //设置定位间隔,单位毫秒,默认为2000ms，最低1000ms。
   mLocationOption.setInterval(1000);
   

5. 设置定位同时是否需要返回地址描述。

//设置是否返回地址信息（默认返回地址信息）
mLocationOption.setNeedAddress(true);

6. 设置是否允许模拟软件Mock位置结果，多为模拟GPS定位结果，默认为true，允许模拟位置。

//设置是否允许模拟位置,默认为true，允许模拟位置
mLocationOption.setMockEnable(true);

7. 设置定位请求超时时间，默认为30秒。

//单位是毫秒，默认30000毫秒，建议超时时间不要低于8000毫秒。
mLocationOption.setHttpTimeOut(20000);

​ 注意：自 V3.1.0 版本之后setHttpTimeOut(long httpTimeOut)方法不仅会限制低功耗定位、高精度定位两种模式的定位超时时间，同样会作用在仅设备定位时。如果单次定位发生超时情况，定位随即终止；连续定位状态下当前这一次定位会返回超时，但按照既定周期的定位请求会继续发起。

8. 设置是否开启定位缓存机制

   缓存机制默认开启，可以通过以下接口进行关闭。

//关闭缓存机制
mLocationOption.setLocationCacheEnable(false);

​ 当开启定位缓存功能，在高精度模式和低功耗模式下进行的网络定位结果均会生成本地缓存，不区分单次定位还是连续定位。GPS定位结果不会被缓存

6. 启动定位

//给定位客户端对象设置定位参数
mLocationClient.setLocationOption(mLocationOption);
//启动定位
mLocationClient.startLocation();

7.获取定位结果

AMapLocationListener接口只有onLocationChanged方法可以实现，用于接收异步返回的定位结果，回调参数是AMapLocation。

实现监听器

//可以通过类implement方式实现AMapLocationListener接口，也可以通过创造接口类对象的方法实现。以下为后者的举例：
AMapLocationListener mAMapLocationListener = new AMapLocationListener(){
@Override
public void onLocationChanged(AMapLocation amapLocation) {
    
  }
}
//设置定位回调监听
mLocationClient.setLocationListener(mLocationListener);

之后在监听器的回调方法内解析AMapLocation对象。

首先，可以判断AMapLocation对象不为空，当定位错误码类型为0时定位成功。

if (amapLocation != null) {
    if (amapLocation.getErrorCode() == 0) {
//可在其中解析amapLocation获取相应内容。
    }else {
    //定位失败时，可通过ErrCode（错误码）信息来确定失败的原因，errInfo是错误信息，详见错误码表。
    Log.e("AmapError","location Error, ErrCode:"
        + amapLocation.getErrorCode() + ", errInfo:"
        + amapLocation.getErrorInfo());
    }
}

当定位失败时，可通过ErrCode（错误码）信息来确定失败的原因，错误码列表如下：

当定位成功时，可在如上判断中解析amapLocation对象的具体字段，参考如下：

amapLocation.getLocationType();//获取当前定位结果来源，如网络定位结果，详见定位类型表
amapLocation.getLatitude();//获取纬度
amapLocation.getLongitude();//获取经度
amapLocation.getAccuracy();//获取精度信息
amapLocation.getAddress();//地址，如果option中设置isNeedAddress为false，则没有此结果，网络定位结果中会有地址信息，GPS定位不返回地址信息。
amapLocation.getCountry();//国家信息
amapLocation.getProvince();//省信息
amapLocation.getCity();//城市信息
amapLocation.getDistrict();//城区信息
amapLocation.getStreet();//街道信息
amapLocation.getStreetNum();//街道门牌号信息
amapLocation.getCityCode();//城市编码
amapLocation.getAdCode();//地区编码
amapLocation.getAoiName();//获取当前定位点的AOI信息
amapLocation.getBuildingId();//获取当前室内定位的建筑物Id
amapLocation.getFloor();//获取当前室内定位的楼层
amapLocation.getGpsAccuracyStatus();//获取GPS的当前状态
//获取定位时间
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
Date date = new Date(amapLocation.getTime());
df.format(date);

AMapLocation核心方法解析

下表是AMapLocation类的核心方法，是上一章节代码段中方法的详细展开，可在参考手册AMapLocation类中查阅其他未展示方法。

8. 停止定位

mLocationClient.stopLocation();//停止定位后，本地定位服务并不会被销毁

销毁定位客户端

销毁定位客户端之后，若要重新开启定位请重新New一个AMapLocationClient对象。

mLocationClient.onDestroy();//销毁定位客户端，同时销毁本地定位服务。

常见问题

1. 企业开发者和个人开发者有什么区别？

个人开发者和企业开发者在申请流程、服务调用场景和权限上都是有差别的。

1. 申请流程

   1. 个人开发者：填写个人信息（包括：姓名、手机、邮箱等），信息验证成功后，即可成为高德个人开发者。

   2. 企业开发者：企业用户需填写企业信息并提交企业营业证照扫描件，我们会在后台对企业资质进行审核，审核时间为3个工作日内，审核通过即可成为企业开发者。

      审核期间，申请企业享受个人开发者权限。

2. 服务场景及权限

3. 服务调用量配额说明

您可以在我的控制台->帐户权限里，查看自己的帐户身份。如果您正在申请企业权限，账户身份显示：个人开发者，审核通过，自动升级为企业开发者。

如果您的企业权限未通过审核，账户身份显示：个人开发者，并提示未通过原因，您可重新申请。

2. 如何获得更准确的定位？

Android除了系统（基站、WiFi、GPS等下拉图标开关）的开关，以及Android系统设置选项（位置信息访问权限），还包括手机上的安全软件（例如360、安全管家或系统自带的安全中心）针对app的定位权限设置；

如果不同的设置对你的App没有开启定位权限，会造成不能定位或者只能够采用一种（GPS、WiFi和基站）方式定位，导致定位精度达不到要求。

3. 为什么设备无法定位？

无法定位的原因有很多种，您可以通过定位SDK的AMapLocation类提供的getErrorCode()方法获取错误码信息；通过getLocationDetail()方法和getErrorInfo()方法获取定位和错误信息。

可根据错误码对应参考错误码表。

1. 网络问题

   多为网络不通畅，或者网络传输劫持问题导致。

   解决办法：检查网络是否通畅，更换新网络请求定位，或者将设置的定位超时时间延长（SDK默认值30秒）。

2. 室内发起GPS定位

   室内环境GPS无法链接卫星，需要到室外环境才可以正常定位。

   解决办法：高精度模式下，处于室内环境时请确保设备打开了WIFI（可不链接）模块，网络通畅，SDK会采用网络进行定位；仅设备模式下，请到室外进行定位。

3. Key错误

   请参考：Key错误问题解决办法 解决。

4. 计算位置失败

   错误码会为 6，可参考：位置计算失败解决办法 解决。

5. 其他问题

   其他错误很少出现，如果出现的话您可以参考错误码表给出的解决办法进行解决。

4. 如何检测Android手机的定位权限？

Android 6.0 之前的系统级定位权限检测接口存在权限判断失准的问题，这导致如果单纯依赖系统接口进行定位权限判断会造成大量设备上定位权限检测不准的情况出现。

所以在 Android 定位SDK 2.9.0 版本中增加了错误码13，错误码13包含一种判断和两层意思：

一种判断是校验多种定位数据源是否存在（或的关系）；两层意思是指13本身有可能代表设备定位权限缺失，有可能代表设备定位数据源缺失。因为当定位权限缺失时（无论系统级定位权限检测接口是否准确返回）定位数据源一定会缺失，反之则不是。

如果SDK明确检查出定位权限缺失时会返回错误码12，如果没有检查出来定位权限缺失，但此时所有定位数据源又都不可用，则会返回13。无论返回的是12或者是13，都说明设备现在所处环境不足以完成定位功能。

所以可以对定位 SDK 的错误码12和13做联合判断，达到检测定位权限的效果。

5. GPS定位时返回的地址有可能为空，怎么办？

为了保证定位速度，当定位类型为GPS时，定位SDK内部获取逆地理信息采用的是异步方式（这种方式有可能造成第一次GPS定位时没有逆地理信息，这样就会造成获取不到地址信息的情况。
低功耗定位模式不受影响，高精度和仅设备定位模式均有可能出现这种情况。

如果业务对地址信息特别依赖的话，建议定位SDK返回的经纬度信息之后通过以下两种方式中的任意一种获取地址信息：

1、如果APP中集成有高德地图SDK，建议使用地图SDK中逆地理接口获取地址信息，具体方法请参考：逆地理编码

2、如果APP中没有集成高德地图SDK，建议使用Web服务API的逆地理编码获取地址信息，开发指南请参考：逆地理编码

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

目前高德地图SDK完全免费，且不限制日配额。