高德android api 开发指南

API 简介
什么是高德地图Android API？
高德地图Android API 版是一套基于Android 1.6 及以上设备的应用程序接口，通过该接口，用户可以轻松访问高德地图服务和数据，构建功能丰富、交互性强的地图应用程序。

高德地图Android API 不仅包含构建地图的基本接口，还提供了诸如矢量地图、栅格地图、地图定位（GPS、基站、WiFi）、本地搜索、路线规划等数据服务，用户可以根据自己的需要进行选择。

面向的读者
本API 是提供给具有一定Android 编程经验和了解面向对象概念的读者使用的。

此外，读者还应该对地图产品有一定的了解。

用户在使用中遇到任何问题，可以通过问答社区反馈给我们。

兼容性
系统：支持Android 1.6 及以上系统。

注意事项
下面介绍在程序开发中需注意的问题：必须在manifest 中设置相应的权限，代码如下：
源码复制打印关于
1<uses-permission
2android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permis sion>
3<uses-permission
4android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permissi on>
5<uses-permission
6android:name="android.permission.INTERNET"></uses-permission>
7<uses-permission
8android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permissi on>
9<uses-permission
10android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permis sion>
11<uses-permission
12android:name="android.permission.READ_PHONE_STATE"></uses-permission> 13<uses-permission
14android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission> 15<uses-permission
16android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission> 地图显示
如何把API 添加到我的Android 工程中？
首先创建工程，并在工程Build Path>Configure Build Path…>libraries 中选择“Add Externel JARs…”，选定MapApi.jar，点击OK，这样就可以将高德地图Android API 库文件引入。

然后在工程Build Path>Configure Build Path…>Order and Export 中将引入的库文件MapApi.jar 选中，点击OK，这样您就可以在您的程序中使用高德地图API 了。

栅格地图显示
MapActivity 是一个抽象类，任何想要显示MapView 的activity 都需要派生自MapActivity。

并且在其派生类的onCreate() 中，都要创建一个MapView 实例。

源码复制打印关于
17public class GridMapView extends MapActivity{
18private MapView mMapView;
19private MapController mMapController;
20private GeoPoint point;
21@Override
22/**
23*显示栅格地图，启用内置缩放控件，并用MapController 控制地图的中心点及Zoom 级别24*/
25protected void onCreate(Bundle savedInstanceState) {
26// TODO Auto-generated method stub
27super.onCreate(savedInstanceState);
28setContentView(yout.mapview);
29mMapView = (MapView) findViewById(R.id.mapView);
30mMapView.setBuiltInZoomControls(true); //设置启用内置的缩放控件
31mMapController = mMapView.getController(); // 得到mMapView 的控制权,可以用它控制和驱动平移和缩放
32point = new GeoPoint((int) (39.982378 * 1E6),
33(int) (116.304923 * 1E6)); //用给定的经纬度构造一个GeoPoint，单位是微度(度* 1E6)
34mMapController.setCenter(point); //设置地图中心点
35mMapController.setZoom(12); //设置地图zoom 级别
36}
37}
在布局xml 中添加地图控件：
源码复制打印关于
38<?xml version="1.0" encoding="utf-8"?>
39<LinearLayout
xmlns:android="/apk/res/android"
40xmlns:autonavi="/apk/res/com.AMap"
41android:orientation="vertical" android:layout_width="fill_parent"
42android:layout_height="fill_parent">
43<com.amap.mapapi.map.MapView android:id="@+id/mapView"
44android:layout_width="fill_parent" android:layout_height="fill_parent"
45android:clickable="true"
46/>
47</LinearLayout>
结果见图3-1 栅格地图显示效果图：
图3-1 栅格地图显示效果图
矢量地图显示
将libminimapv320.so 复制到工程目录下的libs\armeabi，目录结构见图3-2 工程目录结构图：
图3-2 工程目录结构图
代码如下：
源码复制打印关于48public class VectorMapView extends MapActivity{
49private MapView mMapView;
50private MapController mMapController;
51private GeoPoint point;
52@Override
53/**
54*显示矢量地图，将libminimapv300.so 复制到工程目录下的libs\armeabi。

55*启用内置缩放控件，并用MapController 控制地图的中心点及Zoom 级别
56*/
57protected void onCreate(Bundle savedInstanceState) {
58// TODO Auto-generated method stub
59this.setMapMode(MAP_MODE_VECTOR);//设置地图为矢量模式
60super.onCreate(savedInstanceState);
61setContentView(yout.mapview);
62mMapView = (MapView) findViewById(R.id.mapView);
63mMapView.setBuiltInZoomControls(true); //设置启用内置的缩放控件
64mMapController = mMapView.getController(); // 得到mMapView 的控制权,可以用它控制和驱动平移和缩放
65point = new GeoPoint((int) (39.90923 * 1E6),
66(int) (116.397428 * 1E6)); //用给定的经纬度构造一个GeoPoint，单位是微度(度* 1E6)
67mMapController.setCenter(point); //设置地图中心点
68mMapController.setZoom(12); //设置地图zoom 级别
69}
70}
结果见图3-3 矢量地图显示效果图：
图3-3 矢量地图显示效果图定位信息
API 如何获取定位信息
高德地图Android API 中提供了GPS 和网络(基站和WiFi)定位。

如果使用此功能，必须注册GPS 和网络的使用权限，请参考注意事项。

在获取用户位置时，优先使用GPS 进行定位；如果GPS 定位没有打开或者没有可用位置信息，则判断是否通过网络（基站和WiFi）连接，如果是，高德地图会根据手机所在环境选择WiFi 或者基站获取用户当前位置。

源码复制打印关于71public class LocationManager extends Activity {
72private LocationManagerProxy locationManager = null;
73private static final long mLocationUpdateMinTime = 0;
74private static final float mLocationUpdateMinDistance = 0;
75private TextView myLocation;
76/** Called when the activity is first created. */
77@Override
78public void onCreate(Bundle savedInstanceState) {
79super.onCreate(savedInstanceState);
80setContentView(yout.location);
81myLocation = (TextView) findViewById(R.id.myLocation);
82locationManager = LocationManagerProxy.getInstance(this);
83}
84@Override
85protected void onPause() {
86// TODO Auto-generated method stub
87super.onPause();
88locationManager.removeUpdates(locationListener);
89}
90@Override
91protected void onResume() {
92// TODO Auto-generated method stub
93super.onResume();
94//获取当前可用的Provider,其中AMapNetwork 为AMap 网络定位(基站和WiFi)
95for (final String provider : locationManager.getProviders(true)) { 96if
(LocationManagerProxy.GPS_PROVIDER.equals(provider)||LocationProviderProx y.AMapNetwork.equals(provider)) {
97locationManager.requestLocationUpdates(provider,
mLocationUpdateMinTime, mLocationUpdateMinDistance,
98 locationListener);
99}
100}
101}
102LocationListener locationListener = new LocationListener() {
103@Override
104public void onLocationChanged(Location location) {
105// TODO Auto-generated method stub
106if (location != null) {
107Double geoLat = location.getLatitude();
108 Double geoLng = location.getLongitude();
109 myLocation.setText("定位成功:(" + geoLng + "," + geoLat + ")");
110}
111}
112@Override
113public void onProviderDisabled(String provider) {
114}
115@Override
116public void onProviderEnabled(String provider) {
117}
118@Override
119public void onStatusChanged(String provider, int status, Bundle extras) {
120}
121};
122}
如何通过MyLocationOverlay 实现自动定位
首先在程序中打开相关权限，然后将MyLocationOverlay 实例添加到MapView 中，并调用enableMyLocation()方法，即可实现当前位置的显示。

如果想让地图跟随当前位置移动，需要继承MyLocationOverlay 并实现其onLocationChanged()方法，调用MapView.getController().animateTo()方法移动地图位置。

源码复制打印关于
123MyLocationOverlay mylocTest = new MyLocationOverlay(MylocationDemo.this, map);
124mylocTest.enableMyLocation();
125mylocTest.enableCompass(); // 打开指南针
126map.getOverlays().add(mylocTest);
结果见图4-1 自动定位图：
图4-1 自动定位图地图图层
地图图层概念
地图可以包含一个或多个图层，每个图层在各个级别都是由若干张图块组成的，它们覆盖了地球的整个表面。

例如，用户所看到包括街道、兴趣点、学校、公园等内容的地图展现就是一个图层，另外，实时路况、轨道交通等的展现也是通过图层来实现的。

底图
基本的地图图层，包括若干个缩放级别，显示基本的地图信息，包括道路、街道、学校、公园等内容。

实时路况
高德地图提供北京，上海，广州，深圳，天津，重庆，沈阳，长春，石家庄，太原，西安，成都，武汉，南京，杭州，福州，青岛，大连，宁波，无锡，常州，厦门，东莞，珠海等24个城市的实时交通路况查询。

在地图中显示路况信息息示例如下：
源码复制打印关于 mMapView.setTraffic(true);//显示实时路况
运行程序，结果见图5-1 实时路况效果图：
地图覆盖物
概述
所有叠加或覆盖到地图的内容，统称为地图覆盖物。

如标注、矢量图形元素（（包括：折线和多边形和圆））、定位图标等。

覆盖物拥有自己的地理坐标，当您拖动或缩放地图时，它们会相应的移动。

高德地图Android API 提供了如下几种覆盖物：
Overlay：覆盖物的抽象基类，所有的覆盖物均继承此类的方法，实现用户自定义图层显示。

MyLocationOverlay：一个负责显示用户当前位置的Overlay。

ItemizedOverlay：Overlay 的一个基类，包含了一个OverlayItem 列表，相当于一组分条的Overlay，通过继承此类，将一组兴趣点显示在地图上。

PoiOverlay：本地搜索图层，提供某一特定地区的位置搜索服务，比如在北京市搜索“天安门”，通过此图层将包含“天安门”关键字的标注显示在地图上。

RouteOverlay：公交，驾车导航线路图层，将公交、驾车出行方案的路线及关键点显示在地图上。

覆盖物的抽象基类（Overlay）
一般来说，在MapView 中添加一个Overlay 需要经过以下步骤：
自定义类继承Overlay，并Override 其draw()方法可以实现点，线，面等的显示，如果需要点击、按键、触摸等交互操作，还需Override onT ap()等方法。

添加到MapView 的覆盖物中:
源码复制打印关于128publicclass MyOverlay extends Overlay{
129@Override
130public void draw(Canvas canvas, MapView mapView, boolean shadow) { 131// TODO Auto-generated method stub
132super.draw(canvas, mapView, shadow);
133Point screenPts = new Point();
134mapView.getProjection().toPixels(point, screenPts);
135//---add the marker---
136Bitmap bmp = BitmapFactory.decodeResource(
137getResources(), R.drawable.da_marker_red);
138canvas.drawBitmap(bmp, screenPts.x, screenPts.y-50, null);
139Paint paintText = new Paint();
140paintText.setTextSize(18);
141paintText.setColor(Color.BLACK);
142canvas.drawText("★AMap", screenPts.x, screenPts.y, paintText); // 绘制文本
143Paint mCirclePaint = new Paint();
144mCirclePaint.setAntiAlias(true);
145mCirclePaint.setColor(Color.BLUE);
146mCirclePaint.setAlpha(50);
147mCirclePaint.setStyle(Style.FILL);
148canvas.drawCircle(screenPts.x+150, screenPts.y, 50, mCirclePaint);
149Paint paintLine = new Paint();
150paintLine.setColor(Color.RED);
151paintLine.setStrokeWidth(3.0f);
152paintLine.setStyle(Paint.Style.STROKE);
153canvas.drawLine(screenPts.x-100, screenPts.y, screenPts.x, screenPts.y-200, paintLine);
154}
155@Override
156public boolean onTap(GeoPoint arg0, MapView arg1) {
157// TODO Auto-generated method stub
158return super.onTap(arg0, arg1);
159}
160}
添加到MapView 的覆盖物中：
源码复制打印关于161mMapView.getOverlays().add(new MyOverlay());
运行结果见图6-1 覆盖物效果图：
当前位置（MyLocationOverlay）
将MyLocationOverlay 添加到覆盖物中，能够实现在地图上显示当前位置的图标以及指南针：
源码复制打印关于
162MyLocationOverlay mylocTest = new MyLocationOverlay(MylocationDemo.this, map);
163mylocTest.enableMyLocation();
164mylocTest.enableCompass(); // 打开指南针
165map.getOverlays().add(mylocTest);
运行结果见图6-2 当前位置效果图：
图6-2 当前位置效果图
分条目覆盖物（ItemizedOverlay）
某个类型的覆盖物，包含多个类型相同、显示方式相同、处理方式相同的项时，使用此类：
自定义类继承ItemizedOverlay，并Override 其draw() 方法，如果需要点击、按键、触摸等交互操作，还需Override onT ap() 等方法。

源码复制打印关于166class OverItemT extends ItemizedOverlay<overlayitem> {
167private List<overlayitem> GeoList = new ArrayList<overlayitem>();
168private Drawable marker;
169private Context mContext;
170private double mLat1 = 39.9022; // point1 纬度
171private double mLon1 = 116.3922; // point1 经度
172private double mLat2 = 39.607723;
173private double mLon2 = 116.397741;
174private double mLat3 = 39.917723;
175private double mLon3 = 116.6552;
176public OverItemT(Drawable marker, Context context) {
177super(boundCenterBottom(marker));
178this.marker = marker;
179this.mContext = context;
180// 用给定的经纬度构造GeoPoint，单位是微度(度* 1E6)
181GeoPoint p1 = new GeoPoint((int) (mLat1 * 1E6), (int) (mLon1 * 1E6));
182GeoPoint p2 = new GeoPoint((int) (mLat2 * 1E6), (int) (mLon2 * 1E6));
183GeoPoint p3 = new GeoPoint((int) (mLat3 * 1E6), (int) (mLon3 * 1E6));
184// 构造OverlayItem 的三个参数依次为：item 的位置，标题文本，文字片段
185GeoList.add(new OverlayItem(p1, "P1", "point1"));
186GeoList.add(new OverlayItem(p2, "P2", "point2"));
187GeoList.add(new OverlayItem(p3, "P3", "point3"));
188populate(); //createItem(int)方法构造item。

一旦有了数据，在调用其它方法前，首先调用这个方法
189}
190@Override
191public void draw(Canvas canvas, MapView mapView, boolean shadow) { 192// Projection 接口用于屏幕像素点坐标系统和地球表面经纬度点坐标系统之间的变换
193Projection projection = mapView.getProjection();
194for (int index = size() -1; index >= 0; index--) { // 遍历GeoList
195OverlayItem overLayItem = getItem(index); // 得到给定索引的item
196String title= overLayItem.getTitle();
197// 把经纬度变换到相对于MapView 左上角的屏幕像素坐标
198Point point = projection.toPixels(overLayItem.getPoint(), null);
199// 可在此处添加您的绘制代码
200Paint paintText = new Paint();
201paintText.setColor(Color.BLACK);
202paintText.setTextSize(15);
203canvas.drawText(title, point.x-30, point.y -25, paintText); // 绘制文本204}
205super.draw(canvas, mapView, shadow);
206//调整一个drawable 边界，使得（0，0）是这个drawable 底部最后一行中心的一个像素207 boundCenterBottom(marker);
208 }
209 @Override
210protected OverlayItem createItem(int i) {
211// TODO Auto-generated method stub
212return GeoList.get(i);
213}
214@Override
215public int size() {
216// TODO Auto-generated method stub
217return GeoList.size();
218 }
219 @Override
220// 处理当点击事件
221protected boolean onTap(int i) {
222 setFocus(GeoList.get(i));
223Toast.makeText(this.mContext, GeoList.get(i).getSnippet(),
224Toast.LENGTH_SHORT).show();
225return true;
226}
227@Override
228public boolean onTap(GeoPoint point, MapView mapView) {
229// TODO Auto-generated method stub
230return super.onTap(point, mapView);
231 }
232}
添加到MapView 的覆盖物中：
源码复制打印关于
233Drawable marker = getResources().getDrawable(R.drawable.da_marker_red);
//得到需要标在地图上的资源
234marker.setBounds(0, 0, marker.getIntrinsicWidth(), marker
235.getIntrinsicHeight()); //为maker 定义位置和边界
236 mMapView.getOverlays().add(new OverItemT(marker, this)); //添加ItemizedOverlay 实例到mMapView
点击其中一个图标，运行结果见图6-3 分条目覆盖效果图：
图6-3 分条目覆盖效果图
本地搜索覆盖物（PoiOverlay）
请参见PoiSearch 及PoiOverlay 的类参考。

驾车、公交路线覆盖物（RouteOverlay）
请参见驾车路线搜索及RouteOverlay 和公交路线搜索及RouteOverlay 的类参考。

地理编码
AMap Geocoding 仅支持中国范围内的地理及逆地理编码，且只支持中文的中国地图数据，不支持英文的或汉语拼音的中国地图数据。

根据经纬度获取地址描述
代码如下：
源码复制打印关于237double mLat = 39.982402;
238double mLon = 116.305304;
239// 用给定的经纬度构造一个GeoPoint，单位是微度(度* 1E6)
240GeoPoint geo = new GeoPoint((int) (mLat * 1E6),
241(int) (mLon * 1E6));
242try {
243if (geo.toString() != "") {
244Geocoder mGeocoder01 = new Geocoder(GeocodingDemo.this);
245int x = geo.getLatitudeE6(); // 得到geo 纬度，单位微度(度* 1E6)
246double x1 = ((double) x) / 1000000;
247int y = geo.getLongitudeE6(); // 得到geo 经度，单位微度(度* 1E6)
248double y1 = ((double) y) / 1000000;
249//得到逆理编码，参数分别为：纬度，经度，最大结果集
250List<address>lstAddress = mGeocoder01
251.getFromLocation(x1, y1, 3);
252if (lstAddress.size()!=0) {
253//Toast 输出geo 编码得到的地名
254for (int i = 0; i < lstAddress.size(); ++i) {
255Address adsLocation = lstAddress.get(i);
256 Toast.makeText(getApplicationContext(),
257adsLocation.getFeatureName().toString(),
258Toast.LENGTH_LONG).show();
259Log.i(TAG, "Address found = "+ adsLocation.toString());
260}
261} else {
262Log.i(TAG, "Address GeoPoint NOT Found.");
263}
264}
265} catch (Exception e) {
266e.printStackTrace();
267Toast.makeText(getApplicationContext(), "连接错误！", 268Toast.LENGTH_SHORT).show();
269}
结果见图7-1 根据经纬度获取地址描述效果图
图7-1 根据经纬度获取地址描述效果图
AMapGeocoding 新增方法。

根据我国政府规定，GPS 数据需要偏转，才能匹配到电子地图上。

如果应用程序从GPS 上得到了经纬度，则需通过getFromRawGpsLocation(double latitude, double longitude, int maxResults) 方法，进行逆地理编码的转换。

搜索服务
高德地图Poi Search API 提供了对POI（Point Of Interesting，兴趣点）的搜索，它使用高德地图，总计包含千万级别的POI。

PoiSearch及PoiOverlay
POI 搜索有三种方式，：关键字搜索、周边搜索、类型搜索等。

关键字搜索：如：搜索北京的“天安门”关键字
源码复制打印关于270PoiSearch poiSearch= new PoiSearch(PoiSearchDemo.this,newPoiSearch.Query("天安门",PoiTypeDef.All, "010")); // "010为北京电话区号"
271PoiPagedResultresult = poiSearch.searchPOI();
周边搜索：AMap 周边2000 米的和“肯德基”相关的POI 点。

源码复制打印关于272GeoPointpoint = new GeoPoint((int) (39.982378 * 1E6),
273(int) (116.304923 * 1E6));//AMap
274 PoiSearch poiSearch = new PoiSearch(PoiSearchDemo.this,
275new PoiSearch.Query("肯德基",PoiTypeDef.All, "010"));//"010 为北京电话区号" poiSearch.setBound(new SearchBound(point, 2000));
276PoiPagedResultresult = poiSearch.searchPOI();
类型搜索:如：搜索在北京和“西单”有关的所有“银行”。

源码复制打印关于277// "010 为北京电话区号",”银行”为类型，更多类型请参考PoiTypeDef 类，如果您想使用278 PoiSearch poiSearch = new PoiSearch(PoiSearchDemo.this,newPoiSearch.Query("西单","银行", "010"));
下面以周边、类型检索为例，介绍如何进行检索并显示覆盖物PoiOverlay：
源码复制打印关于
279GeoPointpoint = new GeoPoint((int) (39.982378 * 1E6),
280 (int) (116.304923 * 1E6));//AMap
281 PoiSearch poiSearch = new PoiSearch(PoiSearchDemo.this,
282new PoiSearch.Query("","银行", "010")); // "010 为城市区号"
poiSearch.setBound(new SearchBound(point, 1000));
283 PoiPagedResultresult =poiSearch.searchPOI();//AMap 周边1000 米内的银行
结果见图8-1 搜索服务效果图：
图8-1 搜索服务效果图
路径规划
驾车路线规划及RouteOverlay
从“天安门”到“大恒科技大厦”的驾车路线：
源码复制打印关于
284GeoPoint startPoint=new GeoPoint(39908717,116397516);
285GeoPoint endPoint=new GeoPoint(39982374,116305141);
286FromAndTo fromAndTo = new FromAndTo(startPoint, endPoint);
287try {
288List<Route>route = Route.calculateRoute(RouteDemo.this, fromAndTo, Route.DrivingDefault);
289// 构造RouteOverlay 参数为MapActivity cnt, Route rt。

这里只取了查到路径的第一条。

290if (route.size() > 0) {
291routeOverlay = new RouteOverlay(RouteDemo.this, route.get(0));
292routeOverlay.registerRouteMessage(RouteDemo.this);//注册人消息处理函数293routeOverlay.addToMap(mv);//加入地图
294}
295} catch (IOException e) {
296e.printStackTrace();
297}
显示结果见图9-1 驾车路线规划效果图：
图9-1 驾车路线规划效果图
公交路线规划及RouteOverlay
从“天安门”到“大恒科技大厦”的驾车路线：
源码复制打印关于
298GeoPoint startPoint=newGeoPoint(39908717,116397516);
299GeoPoint endPoint=newGeoPoint(39982374,116305141);
300FromAndTo fromAndTo = newFromAndTo(startPoint, endPoint);
301try{
302List<Route>route = Route.calculateRoute(RouteDemo.this, fromAndTo, Route.BusDefault);
303// 构造RouteOverlay 参数为MapActivity cnt, Route rt。

这里只取了查到路径的第一条。

304if(route.size() > 0) {
305routeOverlay= newRouteOverlay(RouteDemo.this, route.get(0));
306routeOverlay.registerRouteMessage(RouteDemo.this);//注册人消息处理函数307routeOverlay.addToMap(mv);//加入地图
308}
309}
310catch(IOException e) {
311e.printStackTrace();
312}
显示结果见图9-2 公交路线规划效果图：
图9-2 公交路线规划效果图。