引入高德定位SDK文檔

官方API接口地址

官方首頁

官方定位SDK使用說明

官方定位SDK參考手冊

官方定位SDK資源下載

引入步驟

申請Key

1. 登錄高德位置服務

登錄方式支持：賬戶月劈、手機號馍忽、淘寶型宝、支付寶、微博和QQ捂襟。

2. 驗證手機與郵箱

驗證手機與郵箱申請成為開發(fā)者咬腕，同時也可以進行企業(yè)認證，獲取更多服務葬荷。

成為個人開發(fā)和成為企業(yè)開發(fā)者涨共。

3. 申請開發(fā)密鑰（key）

成為開發(fā)者之后，在控制臺的key管理中就可以申請創(chuàng)建新密鑰宠漩。

使用

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. 聲明權(quán)限

Android 6.0及以上系統(tǒng)可以參考Android 6.0權(quán)限說明章節(jié)。

1. <!--用于進行網(wǎng)絡定位-->
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission>
   <!--用于訪問GPS定位-->
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
   <!--用于獲取運營商信息，用于支持提供運營商信息相關(guān)的接口-->
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
   <!--用于訪問wifi網(wǎng)絡信息魁索，wifi信息會用于進行網(wǎng)絡定位-->
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
   <!--用于獲取wifi的獲取權(quán)限融撞，wifi信息會用來進行網(wǎng)絡定位-->
   <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
   <!--用于訪問網(wǎng)絡，網(wǎng)絡定位需要上網(wǎng)-->
   <uses-permission android:name="android.permission.INTERNET"></uses-permission>
   <!--用于讀取手機當前的狀態(tài)-->
   <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
   <!--用于寫入緩存數(shù)據(jù)到擴展存儲卡-->
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
   <!--用于申請調(diào)用A-GPS模塊-->
   <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS"></uses-permission>
   <!--用于申請獲取藍牙信息進行室內(nèi)定位-->
   <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">//開發(fā)者申請的key               
</meta-data>

獲取我的Key粗蔚。

4.初始化定位

在主線程中聲明AMapLocationClient類對象尝偎，需要傳Context類型的參數(shù)。推薦用getApplicationContext()方法獲取全進程有效的context鹏控。

//聲明AMapLocationClient類對象
public AMapLocationClient mLocationClient = null;
//初始化定位
mLocationClient = new AMapLocationClient(getApplicationContext());

5.配置參數(shù)并啟動定位

1. 創(chuàng)建AMapLocationClientOption對象

//聲明AMapLocationClientOption對象
public AMapLocationClientOption mLocationOption = null;
//初始化AMapLocationClientOption對象
mLocationOption = new AMapLocationClientOption();

AMapLocationClientOption核心方法解析:

下表是設置定位參數(shù)的核心方法冬念，是以下配置參數(shù)代碼段中方法的詳細展開。

2. 選擇定位場景

   說明：該部分功能從定位SDK v3.7.0開始提供。如果開發(fā)者選擇了對應的定位場景浦马，那么則不用自行設置AMapLocationClientOption中的其他參數(shù)时呀，SDK會根據(jù)選擇的場景自行定制option參數(shù)的值，當然開發(fā)者也可以在基礎上進行自行設置晶默。實際按最后一次設置的參數(shù)值生效谨娜。

   目前支持3種定位場景的設置：簽到、出行磺陡、運動趴梢。默認無場景漠畜。

/**
     * 設置定位場景，目前支持三種場景（簽到坞靶、出行憔狞、運動，默認無場景）
     */
    mLocationOption.setLocationPurpose(AMapLocationClientOption.AMapLocationPurpose.SignIn);
    if(null != locationClient){
      mLocationClient.setLocationOption(option);
      //設置場景模式后最好調(diào)用一次stop彰阴，再調(diào)用start以保證場景模式生效
      mLocationClient.stopLocation();
      mLocationClient.startLocation();
    }

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

3. 選擇定位模式

高德定位服務包含GPS和網(wǎng)絡定位（Wi-Fi和基站定位）兩種能力叨橱。定位SDK將GPS焦履、網(wǎng)絡定位能力進行了封裝，以三種定位模式對外開放雏逾，SDK默認選擇使用高精度定位模式。

高精度定位模式：會同時使用網(wǎng)絡定位和GPS定位郑临，優(yōu)先返回最高精度的定位結(jié)果栖博，以及對應的地址描述信息。

//設置定位模式為AMapLocationMode.Hight_Accuracy厢洞，高精度模式仇让。
mLocationOption.setLocationMode(AMapLocationMode.Hight_Accuracy);

? 低功耗定位模式：不會使用GPS和其他傳感器，只會使用網(wǎng)絡定位（Wi-Fi和基站定位）躺翻；

//設置定位模式為AMapLocationMode.Battery_Saving丧叽，低功耗模式。
mLocationOption.setLocationMode(AMapLocationMode.Battery_Saving);

? 僅用設備定位模式：不需要連接網(wǎng)絡公你，只使用GPS進行定位踊淳，這種模式下不支持室內(nèi)環(huán)境的定位，需要在室外環(huán)境下才可以成功定位陕靠。注意狼犯，自 v2.9.0 版本之后集灌，僅設備定位模式下支持返回地址描述信息。

//設置定位模式為AMapLocationMode.Device_Sensors，僅設備模式绎狭。
mLocationOption.setLocationMode(AMapLocationMode.Device_Sensors);

4. 配置定位次數(shù)

   1. 設置單次定位

      如果您需要使用單次定位，需要進行如下設置：

   //獲取一次定位結(jié)果：
   //該方法默認為false芙扎。
   mLocationOption.setOnceLocation(true);
   
   //獲取最近3s內(nèi)精度最高的一次定位結(jié)果：
   //設置setOnceLocationLatest(boolean b)接口為true负乡，啟動定位時SDK會返回最近3s內(nèi)精度最高的一次定位結(jié)果榜田。如果設置其為true，setOnceLocation(boolean b)接口也會被設置為true锻梳，反之不會箭券，默認為false。
   mLocationOption.setOnceLocationLatest(true);
   
   

   2. 自定義連續(xù)定位

   SDK默認采用連續(xù)定位模式唱蒸，時間間隔2000ms邦鲫。如果您需要自定義調(diào)用間隔：

   //設置定位間隔,單位毫秒,默認為2000ms，最低1000ms神汹。
   mLocationOption.setInterval(1000);
   

5. 設置定位同時是否需要返回地址描述庆捺。

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

6. 設置是否允許模擬軟件Mock位置結(jié)果，多為模擬GPS定位結(jié)果屁魏，默認為true滔以，允許模擬位置。

//設置是否允許模擬位置,默認為true氓拼，允許模擬位置
mLocationOption.setMockEnable(true);

7. 設置定位請求超時時間你画，默認為30秒。

//單位是毫秒桃漾，默認30000毫秒坏匪，建議超時時間不要低于8000毫秒。
mLocationOption.setHttpTimeOut(20000);

? 注意：自 V3.1.0 版本之后setHttpTimeOut(long httpTimeOut)方法不僅會限制低功耗定位撬统、高精度定位兩種模式的定位超時時間适滓，同樣會作用在僅設備定位時。如果單次定位發(fā)生超時情況恋追，定位隨即終止凭迹；連續(xù)定位狀態(tài)下當前這一次定位會返回超時，但按照既定周期的定位請求會繼續(xù)發(fā)起苦囱。

8. 設置是否開啟定位緩存機制

   緩存機制默認開啟嗅绸，可以通過以下接口進行關(guān)閉。

//關(guān)閉緩存機制
mLocationOption.setLocationCacheEnable(false);

? 當開啟定位緩存功能撕彤，在高精度模式和低功耗模式下進行的網(wǎng)絡定位結(jié)果均會生成本地緩存鱼鸠，不區(qū)分單次定位還是連續(xù)定位。GPS定位結(jié)果不會被緩存

6. 啟動定位

//給定位客戶端對象設置定位參數(shù)
mLocationClient.setLocationOption(mLocationOption);
//啟動定位
mLocationClient.startLocation();

7.獲取定位結(jié)果

AMapLocationListener接口只有onLocationChanged方法可以實現(xiàn)羹铅，用于接收異步返回的定位結(jié)果瞧柔，回調(diào)參數(shù)是AMapLocation。

實現(xiàn)監(jiān)聽器

//可以通過類implement方式實現(xiàn)AMapLocationListener接口睦裳，也可以通過創(chuàng)造接口類對象的方法實現(xiàn)造锅。以下為后者的舉例：
AMapLocationListener mAMapLocationListener = new AMapLocationListener(){
@Override
public void onLocationChanged(AMapLocation amapLocation) {
    
  }
}
//設置定位回調(diào)監(jiān)聽
mLocationClient.setLocationListener(mLocationListener);

之后在監(jiān)聽器的回調(diào)方法內(nèi)解析AMapLocation對象。

首先廉邑，可以判斷AMapLocation對象不為空哥蔚，當定位錯誤碼類型為0時定位成功倒谷。

if (amapLocation != null) {
    if (amapLocation.getErrorCode() == 0) {
//可在其中解析amapLocation獲取相應內(nèi)容。
    }else {
    //定位失敗時糙箍，可通過ErrCode（錯誤碼）信息來確定失敗的原因渤愁，errInfo是錯誤信息，詳見錯誤碼表深夯。
    Log.e("AmapError","location Error, ErrCode:"
        + amapLocation.getErrorCode() + ", errInfo:"
        + amapLocation.getErrorInfo());
    }
}

當定位失敗時抖格，可通過ErrCode（錯誤碼）信息來確定失敗的原因，錯誤碼列表如下：

當定位成功時胧洒，可在如上判斷中解析amapLocation對象的具體字段，參考如下：

amapLocation.getLocationType();//獲取當前定位結(jié)果來源墨状，如網(wǎng)絡定位結(jié)果卫漫，詳見定位類型表
amapLocation.getLatitude();//獲取緯度
amapLocation.getLongitude();//獲取經(jīng)度
amapLocation.getAccuracy();//獲取精度信息
amapLocation.getAddress();//地址，如果option中設置isNeedAddress為false肾砂，則沒有此結(jié)果列赎，網(wǎng)絡定位結(jié)果中會有地址信息，GPS定位不返回地址信息镐确。
amapLocation.getCountry();//國家信息
amapLocation.getProvince();//省信息
amapLocation.getCity();//城市信息
amapLocation.getDistrict();//城區(qū)信息
amapLocation.getStreet();//街道信息
amapLocation.getStreetNum();//街道門牌號信息
amapLocation.getCityCode();//城市編碼
amapLocation.getAdCode();//地區(qū)編碼
amapLocation.getAoiName();//獲取當前定位點的AOI信息
amapLocation.getBuildingId();//獲取當前室內(nèi)定位的建筑物Id
amapLocation.getFloor();//獲取當前室內(nèi)定位的樓層
amapLocation.getGpsAccuracyStatus();//獲取GPS的當前狀態(tài)
//獲取定位時間
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
Date date = new Date(amapLocation.getTime());
df.format(date);

AMapLocation核心方法解析

下表是AMapLocation類的核心方法粥谬，是上一章節(jié)代碼段中方法的詳細展開肛根，可在參考手冊AMapLocation類中查閱其他未展示方法。

8. 停止定位

mLocationClient.stopLocation();//停止定位后派哲，本地定位服務并不會被銷毀

銷毀定位客戶端

銷毀定位客戶端之后，若要重新開啟定位請重新New一個AMapLocationClient對象掺喻。

mLocationClient.onDestroy();//銷毀定位客戶端芭届，同時銷毀本地定位服務。

常見問題

1. 企業(yè)開發(fā)者和個人開發(fā)者有什么區(qū)別感耙？

個人開發(fā)者和企業(yè)開發(fā)者在申請流程褂乍、服務調(diào)用場景和權(quán)限上都是有差別的。

1. 申請流程

   1. 個人開發(fā)者：填寫個人信息（包括：姓名即硼、手機逃片、郵箱等），信息驗證成功后只酥，即可成為高德個人開發(fā)者褥实。

   2. 企業(yè)開發(fā)者：企業(yè)用戶需填寫企業(yè)信息并提交企業(yè)營業(yè)證照掃描件，我們會在后臺對企業(yè)資質(zhì)進行審核裂允，審核時間為3個工作日內(nèi)损离，審核通過即可成為企業(yè)開發(fā)者。

      審核期間绝编，申請企業(yè)享受個人開發(fā)者權(quán)限僻澎。

2. 服務場景及權(quán)限

3. 服務調(diào)用量配額說明

您可以在我的控制臺->帳戶權(quán)限里，查看自己的帳戶身份涮帘。如果您正在申請企業(yè)權(quán)限拼苍，賬戶身份顯示：個人開發(fā)者，審核通過调缨，自動升級為企業(yè)開發(fā)者疮鲫。

如果您的企業(yè)權(quán)限未通過審核，賬戶身份顯示：個人開發(fā)者同蜻，并提示未通過原因棚点，您可重新申請。

2. 如何獲得更準確的定位湾蔓？

Android除了系統(tǒng)（基站瘫析、WiFi、GPS等下拉圖標開關(guān)）的開關(guān)默责，以及Android系統(tǒng)設置選項（位置信息訪問權(quán)限）贬循，還包括手機上的安全軟件（例如360、安全管家或系統(tǒng)自帶的安全中心）針對app的定位權(quán)限設置桃序；

如果不同的設置對你的App沒有開啟定位權(quán)限杖虾，會造成不能定位或者只能夠采用一種（GPS、WiFi和基站）方式定位媒熊，導致定位精度達不到要求奇适。

3. 為什么設備無法定位？

無法定位的原因有很多種芦鳍，您可以通過定位SDK的AMapLocation類提供的getErrorCode()方法獲取錯誤碼信息嚷往；通過getLocationDetail()方法和getErrorInfo()方法獲取定位和錯誤信息。

可根據(jù)錯誤碼對應參考錯誤碼表柠衅。

1. 網(wǎng)絡問題

   多為網(wǎng)絡不通暢皮仁，或者網(wǎng)絡傳輸劫持問題導致。

   解決辦法：檢查網(wǎng)絡是否通暢，更換新網(wǎng)絡請求定位贷祈，或者將設置的定位超時時間延長（SDK默認值30秒）趋急。

2. 室內(nèi)發(fā)起GPS定位

   室內(nèi)環(huán)境GPS無法鏈接衛(wèi)星，需要到室外環(huán)境才可以正常定位势誊。

   解決辦法：高精度模式下呜达，處于室內(nèi)環(huán)境時請確保設備打開了WIFI（可不鏈接）模塊，網(wǎng)絡通暢粟耻，SDK會采用網(wǎng)絡進行定位闻丑；僅設備模式下，請到室外進行定位勋颖。

3. Key錯誤

   請參考：Key錯誤問題解決辦法 解決嗦嗡。

4. 計算位置失敗

   錯誤碼會為 6，可參考：位置計算失敗解決辦法 解決饭玲。

5. 其他問題

   其他錯誤很少出現(xiàn)侥祭，如果出現(xiàn)的話您可以參考錯誤碼表給出的解決辦法進行解決。

4. 如何檢測Android手機的定位權(quán)限茄厘？

Android 6.0 之前的系統(tǒng)級定位權(quán)限檢測接口存在權(quán)限判斷失準的問題矮冬，這導致如果單純依賴系統(tǒng)接口進行定位權(quán)限判斷會造成大量設備上定位權(quán)限檢測不準的情況出現(xiàn)。

所以在 Android 定位SDK 2.9.0 版本中增加了錯誤碼13次哈，錯誤碼13包含一種判斷和兩層意思：

一種判斷是校驗多種定位數(shù)據(jù)源是否存在（或的關(guān)系）胎署；兩層意思是指13本身有可能代表設備定位權(quán)限缺失，有可能代表設備定位數(shù)據(jù)源缺失窑滞。因為當定位權(quán)限缺失時（無論系統(tǒng)級定位權(quán)限檢測接口是否準確返回）定位數(shù)據(jù)源一定會缺失琼牧，反之則不是。

如果SDK明確檢查出定位權(quán)限缺失時會返回錯誤碼12哀卫，如果沒有檢查出來定位權(quán)限缺失巨坊，但此時所有定位數(shù)據(jù)源又都不可用，則會返回13此改。無論返回的是12或者是13趾撵，都說明設備現(xiàn)在所處環(huán)境不足以完成定位功能。

所以可以對定位 SDK 的錯誤碼12和13做聯(lián)合判斷共啃，達到檢測定位權(quán)限的效果占调。

5. GPS定位時返回的地址有可能為空，怎么辦移剪？

為了保證定位速度究珊，當定位類型為GPS時，定位SDK內(nèi)部獲取逆地理信息采用的是異步方式（這種方式有可能造成第一次GPS定位時沒有逆地理信息挂滓，這樣就會造成獲取不到地址信息的情況苦银。
低功耗定位模式不受影響，高精度和僅設備定位模式均有可能出現(xiàn)這種情況赶站。

如果業(yè)務對地址信息特別依賴的話幔虏，建議定位SDK返回的經(jīng)緯度信息之后通過以下兩種方式中的任意一種獲取地址信息：

1、如果APP中集成有高德地圖SDK贝椿，建議使用地圖SDK中逆地理接口獲取地址信息想括，具體方法請參考：逆地理編碼

2、如果APP中沒有集成高德地圖SDK烙博，建議使用Web服務API的逆地理編碼獲取地址信息瑟蜈，開發(fā)指南請參考：逆地理編碼

6. 是否免費? 調(diào)用有次數(shù)限制嗎？

目前高德地圖SDK完全免費渣窜，且不限制日配額铺根。