引入高德定位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
- 声明Service组件
- 声明权限
Android 6.0及以上系统可以参考Android 6.0权限说明章节。
设置高德Key
//开发者申请的key
获取我的Key。
4.初始化定位
在主线程中声明AMapLocationClient类对象，需要传Context类型的参数。推荐用getApplicationContext()方法获取全进程有效的context。
//声明AMapLocationClient类对象
public AMapLocationClient mLocationClient = null;
//初始化定位
mLocationClient = new AMapLocationClient(getApplicationContext());
5.配置参数并启动定位
- 创建AMapLocationClientOption对象
//声明AMapLocationClientOption对象
public AMapLocationClientOption mLocationOption = null;
//初始化AMapLocationClientOption对象
mLocationOption = new AMapLocationClientOption();
AMapLocationClientOption核心方法解析:
下表是设置定位参数的核心方法，是以下配置参数代码段中方法的详细展开。
| 方法名 | 参数说明 | 返回值说明 | 方法效果 | 默认值 |
|---|---|---|---|---|
| setLocationMode(AMapLocationMode locationMode) | locationMode是定位类型AMapLocationMode的对象，提供三个枚举常量分别代表三种定位模式。Hight_Accuracy：高精度定位模式；Device_Sensors：仅设备定位模式；Battery_Saving：低功耗定位模式； | 返回AMapLocationClientOption类对象 | V2.0.0版本起用于设置SDK定位模式 | Hight_Accuracy默认高精度模式 |
| setLocationCacheEnable(boolean isLocationCacheEnable) | isLocationCacheEnable是布尔型参数，true表示使用定位缓存策略；false表示不使用。 | void | V2.5.0版本起启用缓存策略，SDK将在设备位置未改变时返回之前相同位置的缓存结果。 | true默认启用缓存策略 |
| setInterval(long interval) | interval是长整型参数，用于设定连续定位间隔，毫秒级参数。 | 返回AMapLocationClientOption类对象 | V2.0.0版本起例如向方法传1000，连续定位启动后会以1s为间隔时间返回定位结果。 | 2000 |
| setOnceLocation(boolean isOnceLocation) | isOnceLocation是布尔型参数，true表示启动单次定位，false表示使用默认的连续定位策略。 | 返回AMapLocationClientOption类对象 | V2.0.0版本起传入true，启动定位，AmapLocationClient将会返回一次定位结果。 | false |
| setOnceLocationLatest(booleanisOnceLocationLatest) | isOnceLocationLatest是布尔型参数，true表示获取最近3s内精度最高的一次定位结果；false表示使用默认的连续定位策略。 | 返回AMapLocationClientOption类对象 | V2.6.0版本起出入true，启动定位，AmapLocationClient将会最近3s内精度最高的一次定位结果。 | false |
| setNeedAddress(boolean isNeedAddress) | isNeedAddress是布尔型参数，true表示定位返回经纬度同时返回地址描述（定位类型是网络定位的会返回）；false表示不返回地址描述。 | 返回AMapLocationClientOption类对象 | V2.0.0版本起传入true，启动定位，AmapLocationClient返回经纬度的同时会返回地址描述。注意：模式为仅设备模式(Device_Sensors)时无效。 | true |
| setMockEnable(boolean isMockEnable) | isMockEnable是布尔型参数，true表示允许外界在定位SDK通过GPS定位时模拟位置，false表示不允许模拟GPS位置。 | void | V2.0.0版本起传入true，启动定位，可以通过外界第三方软件对GPS位置进行模拟。注意：模式为低功耗模式(Battery_Saving)时无效。 | false |
| setWifiActiveScan(boolean isWifiActiveScan) | isWifiActiveScan是布尔型参数，true表示会主动刷新设备wifi模块，获取到最新鲜的wifi列表（wifi新鲜程度决定定位精度）；false表示不主动刷新。 | void | V2.0.0版本起传入true，启动定位，AmapLocationClient会驱动设备扫描周边wifi，获取最新的wifi列表（相比设备被动刷新会多消耗一些电量），从而获取更精准的定位结果。注意：模式为仅设备模式(Device_Sensors)时无效 | false |
| setHttpTimeOut(long httpTimeOut) | httpTimeOut是长整型参数，用于设定通过网络定位获取结果的超时时间，毫秒级。 | void | V2.0.0版本起传入20000，代表网络定位超时时间为20秒。 | 30000 |
| setProtocol(int Protocol) | Protocol是整型参数，用于设定网络定位时所采用的协议，提供http/https两种协议。 | void | V2.0.0版本起AMapLocationProtocol.HTTP代表http;AMapLocationProtocol.HTTPS代表https。 |
-
选择定位场景
说明：该部分功能从定位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 定位场景常量如下：
| 枚举常量 | 说明 | 场景配置参数说明 |
|---|---|---|
| SignIn | 签到场景 | 只进行一次定位返回最接近真实位置的定位结果（定位速度可能会延迟1-3s） |
| Transport | 出行场景 | 高精度连续定位，适用于有户内外切换的场景，卫星定位和网络定位相互切换，卫星定位成功之后网络定位不再返回，卫星信号断开之后一段时间才会返回网络结果 |
| Sport | 运动场景 | 高精度连续定位，适用于有户内外切换的场景，卫星定位和网络定位相互切换，卫星定位成功之后网络定位不再返回，卫星信号断开之后一段时间才会返回网络结果 |
- 选择定位模式
高德定位服务包含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);
-
配置定位次数
-
设置单次定位
如果您需要使用单次定位，需要进行如下设置：
//获取一次定位结果： //该方法默认为false。 mLocationOption.setOnceLocation(true); //获取最近3s内精度最高的一次定位结果： //设置setOnceLocationLatest(boolean b)接口为true，启动定位时SDK会返回最近3s内精度最高的一次定位结果。如果设置其为true，setOnceLocation(boolean b)接口也会被设置为true，反之不会，默认为false。 mLocationOption.setOnceLocationLatest(true);- 自定义连续定位
SDK默认采用连续定位模式，时间间隔2000ms。如果您需要自定义调用间隔：
//设置定位间隔,单位毫秒,默认为2000ms，最低1000ms。 mLocationOption.setInterval(1000); -
设置定位同时是否需要返回地址描述。
//设置是否返回地址信息（默认返回地址信息）
mLocationOption.setNeedAddress(true);
- 设置是否允许模拟软件Mock位置结果，多为模拟GPS定位结果，默认为true，允许模拟位置。
//设置是否允许模拟位置,默认为true，允许模拟位置
mLocationOption.setMockEnable(true);
- 设置定位请求超时时间，默认为30秒。
//单位是毫秒，默认30000毫秒，建议超时时间不要低于8000毫秒。
mLocationOption.setHttpTimeOut(20000);
注意：自 V3.1.0 版本之后setHttpTimeOut(long httpTimeOut)方法不仅会限制低功耗定位、高精度定位两种模式的定位超时时间，同样会作用在仅设备定位时。如果单次定位发生超时情况，定位随即终止；连续定位状态下当前这一次定位会返回超时，但按照既定周期的定位请求会继续发起。
-
设置是否开启定位缓存机制
缓存机制默认开启，可以通过以下接口进行关闭。
//关闭缓存机制
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（错误码）信息来确定失败的原因，错误码列表如下：
| 响应码 | 问题说明 | 问题排查策略 |
|---|---|---|
| 0 | 定位成功。 | 可以在定位回调里判断定位返回成功后再进行业务逻辑运算。 |
| 1 | 一些重要参数为空，如context； | 请对定位传递的参数进行非空判断。 |
| 2 | 定位失败，由于仅扫描到单个wifi，且没有基站信息。 | 请重新尝试。 |
| 3 | 获取到的请求参数为空，可能获取过程中出现异常。 | 请对所连接网络进行全面检查，请求可能被篡改。 |
| 4 | 请求服务器过程中的异常，多为网络情况差，链路不通导致 | 请检查设备网络是否通畅，检查通过接口设置的网络访问超时时间，建议采用默认的30秒。 |
| 5 | 请求被恶意劫持，定位结果解析失败。 | 您可以稍后再试，或检查网络链路是否存在异常。 |
| 6 | 定位服务返回定位失败。 | 请获取errorDetail（通过getLocationDetail()方法获取）信息并参考定位常见问题进行解决。 |
| 7 | KEY鉴权失败。 | 请仔细检查key绑定的sha1值与apk签名sha1值是否对应，或通过高频问题查找相关解决办法。 |
| 8 | Android exception常规错误 | 请将errordetail（通过getLocationDetail()方法获取）信息通过工单系统反馈给我们。 |
| 9 | 定位初始化时出现异常。 | 请重新启动定位。 |
| 10 | 定位客户端启动失败。 | 请检查AndroidManifest.xml文件是否配置了APSService定位服务 |
| 11 | 定位时的基站信息错误。 | 请检查是否安装SIM卡，设备很有可能连入了伪基站网络。 |
| 12 | 缺少定位权限。 | 请在设备的设置中开启app的定位权限。 |
| 13 | 定位失败，由于未获得WIFI列表和基站信息，且GPS当前不可用。 | 建议开启设备的WIFI模块，并将设备中插入一张可以正常工作的SIM卡，或者检查GPS是否开启；如果以上都内容都确认无误，请您检查App是否被授予定位权限。 |
| 14 | GPS 定位失败，由于设备当前 GPS 状态差。 | 建议持设备到相对开阔的露天场所再次尝试。 |
| 15 | 定位结果被模拟导致定位失败 | 如果您希望位置被模拟，请通过setMockEnable(true);方法开启允许位置模拟 |
| 16 | 当前POI检索条件、行政区划检索条件下，无可用地理围栏 | 建议调整检索条件后重新尝试，例如调整POI关键字，调整POI类型，调整周边搜区域，调整行政区关键字等。 |
| 18 | 定位失败，由于手机WIFI功能被关闭同时设置为飞行模式 | 建议手机关闭飞行模式，并打开WIFI开关 |
| 19 | 定位失败，由于手机没插sim卡且WIFI功能被关闭 | 建议手机插上sim卡，打开WIFI开关 |
当定位成功时，可在如上判断中解析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类中查阅其他未展示方法。
| 方法 | 返回值 | 返回值说明 | 方法效果 | 备注 |
|---|---|---|---|---|
| getLatitude() | double | 纬度 | 获取纬度 | V2.0.0版本起 |
| getLongitude() | double | 经度 | 获取经度 | V2.0.0版本起 |
| getAccuracy() | float | 精度 | 获取定位精度 单位:米 | V2.0.0版本起 |
| getAltitude() | double | 海拔 | 获取海拔高度信息 | V2.0.0版本起 |
| getSpeed() | float | 速度 | 单位：米/秒 | V2.0.0版本起 |
| getBearing() | float | 方向角 | 获取方向角信息 | V2.0.0版本起 |
| getBuildingId() | String | 室内定位建筑物Id | 获取室内定位建筑物Id | V3.2.0版本起 |
| getFloor() | String | 室内定位楼层 | 获取室内定位楼层 | V3.2.0版本起 |
| getAddress() | String | 地址描述 | 获取地址描述 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getCountry() | String | 国家 | 获取国家名称 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getProvince() | String | 省 | 获取省名称 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getCity() | String | 城市 | 获取城市名称 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getDistrict() | String | 城区 | 获取城区名称 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getStreet() | String | 街道 | 获取街道名称 | V2.3.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getStreetNum() | String | 街道门牌号 | 获取街道门牌号信息 | V2.3.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getCityCode() | String | 城市编码 | 获取城市编码信息 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getAdCode() | String | 区域编码 | 获取区域编码信息 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getPoiName() | String | 当前位置POI名称 | 获取当前位置的POI名称 | V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getAoiName() | String | 当前位置所处AOI名称 | 获取当前位置所处AOI名称 | V2.4.0版本起模式为仅设备模式(Device_Sensors)时无此信息 |
| getGpsAccuracyStatus() | int | 设备当前 GPS 状态 | 获取GPS当前状态，返回值可参考AMapLocation类提供的常量 | V3.1.0版本起模式为仅设备模式(Device_Sensors)时提供此信息 |
| getLocationType() | int | 定位来源 | 获取定位结果来源 | V2.0.0版本起可参考定位类型编码表 |
| getLocationDetail() | String | 定位信息描述 | 定位信息描述 | V2.0.0版本起用于问题排查 |
| getErrorInfo() | String | 定位错误信息描述 | 定位出现异常的描述 | V2.0.0版本起可参考定位错误码表 |
| getErrorCode() | String | 定位错误码 | 定位出现异常时的编码 | V2.0.0版本起可参考定位错误码表 |
8. 停止定位
mLocationClient.stopLocation();//停止定位后，本地定位服务并不会被销毁
销毁定位客户端
销毁定位客户端之后，若要重新开启定位请重新New一个AMapLocationClient对象。
mLocationClient.onDestroy();//销毁定位客户端，同时销毁本地定位服务。
常见问题
1. 企业开发者和个人开发者有什么区别？
个人开发者和企业开发者在申请流程、服务调用场景和权限上都是有差别的。
-
申请流程
个人开发者：填写个人信息（包括：姓名、手机、邮箱等），信息验证成功后，即可成为高德个人开发者。
-
企业开发者：企业用户需填写企业信息并提交企业营业证照扫描件，我们会在后台对企业资质进行审核，审核时间为3个工作日内，审核通过即可成为企业开发者。
审核期间，申请企业享受个人开发者权限。
服务场景及权限
| 区别 | 个人开发者 | 企业开发者 |
|---|---|---|
| 场景 | 1、公司研发技术选型期；2、新产品研发，测试阶段；3、学生、研究所或个人兴趣学习研究 | 1、有营运资质的企业主体；2、有较高服务调用需求,如：已经投放市场，并有一定用户基础的APP、网站或硬件产品； |
| 服务 | 1、使用开放平台除“智能硬件定位服务”外的所有产品和服务（配额见下表）；2、产品经理提供线上技术支持（渠道：论坛、邮箱） | 1、使用开放平台所有服务和产品；2、获得更高服务调用配额（详见下方对照表）；3、高优采纳需求反馈，提供技术支持；4、优先获得商务支持、运营合作机会； |
- 服务调用量配额说明
您可以在我的控制台->帐户权限里，查看自己的帐户身份。如果您正在申请企业权限，账户身份显示：个人开发者，审核通过，自动升级为企业开发者。
如果您的企业权限未通过审核，账户身份显示：个人开发者，并提示未通过原因，您可重新申请。
2. 如何获得更准确的定位？
Android除了系统（基站、WiFi、GPS等下拉图标开关）的开关，以及Android系统设置选项（位置信息访问权限），还包括手机上的安全软件（例如360、安全管家或系统自带的安全中心）针对app的定位权限设置；
如果不同的设置对你的App没有开启定位权限，会造成不能定位或者只能够采用一种（GPS、WiFi和基站）方式定位，导致定位精度达不到要求。
3. 为什么设备无法定位？
无法定位的原因有很多种，您可以通过定位SDK的AMapLocation类提供的getErrorCode()方法获取错误码信息；通过getLocationDetail()方法和getErrorInfo()方法获取定位和错误信息。
可根据错误码对应参考错误码表。
-
网络问题
多为网络不通畅，或者网络传输劫持问题导致。
解决办法：检查网络是否通畅，更换新网络请求定位，或者将设置的定位超时时间延长（SDK默认值30秒）。
-
室内发起GPS定位
室内环境GPS无法链接卫星，需要到室外环境才可以正常定位。
解决办法：高精度模式下，处于室内环境时请确保设备打开了WIFI（可不链接）模块，网络通畅，SDK会采用网络进行定位；仅设备模式下，请到室外进行定位。
-
Key错误
请参考：Key错误问题解决办法 解决。
-
计算位置失败
错误码会为 6，可参考：位置计算失败解决办法 解决。
-
其他问题
其他错误很少出现，如果出现的话您可以参考错误码表给出的解决办法进行解决。
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完全免费，且不限制日配额。