Getting Started

The Android Maps API Developer's Guide assumes you are familiar with the Eclipse environment. Visit Eclipse for further details and installation instructions.

 

If you're new to developing for Android, you should first set up your environment by following the Android SDK Tutorial. Once you've completed installing the SDK starter package, adding Android platforms and other components, download the MapQuest Android Maps API & Samples to get started.

 

From here, you can either import and view the samples provided in the download or create a new Android project and begin development! When creating a new project, import the JAR file into a new folder called libs, then add the JAR file to the build path.

 

And for all OpenStreetMap (OSM) fans, the API also supports OSM tiles and other Open Services. You can access this by simply leaving the android:apiKey attribute blank.

 

 

Contents

Follow the Developer's Guide to learn about the Android Maps API or skip ahead to one of the sections below.

 

 

 

Basic Map

Having done all of the above, you can now begin developing your first basic map.

 

 

Create a new project in Eclipse.

 

Allow Internet access to your application (required for retrieving map tiles) by adding the following Uses Permission to the AndroidManifest.xml:

  <manifest xlmns:android...>
    ...
    <uses-permission android:name="android.permission.INTERNET"/>
  </manifest>

 

Define the ID associated with your map view (android:id), allow for interactivity on your map (android:clickable) and access the default MapQuest tiles (android:apiKey) by replacing the contents of main.xml found in the res/layout/ folder with the following:

  <?xml version="1.0" encoding="utf-8"?>

  <com.mapquest.android.maps.MapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/map"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:clickable="true"
    android:apiKey="YOUR_APPKEY_HERE"
  />

 

Open the .java file located in the src folder and add the following import packages to your project. Alternatively, you can use Eclipse to organize imports automatically by hitting Ctrl+Shift+O (Cmd+Shift+O on Macs).

  import com.mapquest.android.maps.GeoPoint;
  import com.mapquest.android.maps.MapActivity;
  import com.mapquest.android.maps.MapView;

 

And finally, we modify the Activity so it extends MapActivity, set a few map parameters, add some controls, and display the map.

  public class MyBasicMap extends MapActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

      // set the zoom level, center point and enable the default zoom controls 
      MapView map = (MapView) findViewById(R.id.map);
      map.getController().setZoom(9);
      map.getController().setCenter(new GeoPoint(38.892155,-77.036195));
      map.setBuiltInZoomControls(true);
    }

    // return false since no route is being displayed 
    @Override
    public boolean isRouteDisplayed() {
      return false;
    }
  }

 

 

 

Finding Your Location

The following sample can be used to locate your current position.

 

 

In order to enable geolocation, you must allow access to your device's location. Access to the Internet must also be enabled for retrieving map tiles. Add the following to the AndroidManifest.xml:

  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

 

Fine Location is generally collected from the device's GPS while Coarse Location refers to the approximate location using WiFi and/or Cell-ID.

 

Next, allow for interactivity of the map and access the default MapQuest tiles by adding the following to your XML layout. Refer back to the Basic Map sample for further details.

  android:id="@+id/map"
  android:clickable="true"
  android:apiKey="YOUR_APPKEY_HERE"

 

Set your map and add the MyLocationOverlay class that geolocates your current position in the .java file. Organize imports as needed (Ctrl+Shift+O).

  public class MyGeolocationMap extends MapActivity {
    protected MapView map;
    private MyLocationOverlay myLocationOverlay;

    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);
      setupMapView();
      setupMyLocation();
    }

    // set your map and enable default zoom controls 
    private void setupMapView() {
      this.map = (MapView) findViewById(R.id.map);
      map.setBuiltInZoomControls(true);
    }

    // set up a MyLocationOverlay and execute the runnable once we have a location fix 
    private void setupMyLocation() {
      this.myLocationOverlay = new MyLocationOverlay(this, map);
      myLocationOverlay.enableMyLocation();
      myLocationOverlay.runOnFirstFix(new Runnable() {
        @Override
        public void run() {
          GeoPoint currentLocation = myLocationOverlay.getMyLocation();
          map.getController().animateTo(currentLocation);
          map.getController().setZoom(14);
          map.getOverlays().add(myLocationOverlay);
          myLocationOverlay.setFollowing(true);
        }
      });
    }

    // enable features of the overlay 
    @Override
    protected void onResume() {
      myLocationOverlay.enableMyLocation();
      myLocationOverlay.enableCompass();
      super.onResume();
    }

    // disable features of the overlay when in the background 
    @Override
    protected void onPause() {
      super.onPause();
      myLocationOverlay.disableCompass();
      myLocationOverlay.disableMyLocation();
    }

    @Override
    public boolean isRouteDisplayed() {
      return false;
    }
  }

 

 

 

Drawing Overlays

The following map utilizes PolygonOverlay, LineOverlay and OverlayItem to draw overlays on the map.

 

 

Allow Internet access to your application in the AndroidManifest.xml and update the XML layout to allow interactivity. Refer back to the Basic Map sample for further details.

  <uses-permission android:name="android.permission.INTERNET"/>

 

  android:id="@+id/map"
  android:clickable="true"
  android:apiKey="YOUR_APPKEY_HERE"

 

Add overlays and set an AnnotationView for the POI marker which behaves similar to an InfoWindow. The POI marker, location_marker.png, should be added to the res/drawable folders in Eclipse and will be referenced in the code below. Organize imports as needed (Ctrl+Shift+O).

  public class MyOverlayMap extends MapActivity {
    protected MapView map;
    AnnotationView annotation;

    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

      map = (MapView) findViewById(R.id.map);
      map.getController().setZoom(4);
      map.getController().setCenter(new GeoPoint(38.7217,-112.386036));
      map.setBuiltInZoomControls(true);

      // initialize the annotation to be shown later 
      annotation = new AnnotationView(map);

      addPolyOverlay();
      addLineOverlay();
      addPoiOverlay();
    }

    // add polygon overlay to map 
    private void addPolyOverlay() {
      // set custom polygon style 
      Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
      paint.setColor(Color.BLUE);
      paint.setStyle(Paint.Style.FILL);
      paint.setAlpha(40);

      // list of GeoPoint objects to be used to draw polygon 
      List<GeoPoint> polyData = new ArrayList<GeoPoint>();
      polyData.add(new GeoPoint(41.000702,-109.049979));
      polyData.add(new GeoPoint(41.002528,-102.051699));
      polyData.add(new GeoPoint(36.993105,-102.042215));
      polyData.add(new GeoPoint(36.999073,-109.045178));

      // apply polygon style & data and add to map 
      PolygonOverlay polyOverlay = new PolygonOverlay(paint);
      polyOverlay.setData(polyData);
      map.getOverlays().add(polyOverlay);
    }

    // add line overlay to map 
    private void addLineOverlay() {
      // set custom line style 
      Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
      paint.setColor(Color.BLACK);
      paint.setStyle(Paint.Style.STROKE);
      paint.setStrokeWidth(3);

      // list of GeoPoint objects to be used to draw line 
      List lineData = new ArrayList();
      lineData.add(new GeoPoint(39.739983,-104.984727));
      lineData.add(new GeoPoint(37.441903,-122.141895));

      // apply line style & data and add to map 
      LineOverlay lineOverlay = new LineOverlay(paint);
      lineOverlay.setData(lineData);
      map.getOverlays().add(lineOverlay);
    }

    // add an itemized overlay to map 
    private void addPoiOverlay() {

      // use a custom POI marker by referencing the bitmap file directly,
      // using the filename as the resource ID 
      Drawable icon = getResources().getDrawable(R.drawable.location_marker);
      final DefaultItemizedOverlay poiOverlay = new DefaultItemizedOverlay(icon);

      // set GeoPoints and title/snippet to be used in the annotation view 
      OverlayItem poi1 = new OverlayItem(new GeoPoint (39.739983,-104.984727), "Denver, Colorado", "MapQuest Headquarters");
      poiOverlay.addItem(poi1);
      OverlayItem poi2 = new OverlayItem(new GeoPoint (37.441903,-122.141895), "Palo Alto, California", "AOL Offices");
      poiOverlay.addItem(poi2);

      // add a tap listener for the POI overlay 
      poiOverlay.setTapListener(new ItemizedOverlay.OverlayTapListener() {
      @Override
        public void onTap(GeoPoint pt, MapView mapView) {
           // when tapped, show the annotation for the overlayItem 
           int lastTouchedIndex = poiOverlay.getLastFocusedIndex();
           if(lastTouchedIndex>-1){
               OverlayItem tapped = poiOverlay.getItem(lastTouchedIndex);
               annotation.showAnnotationView(tapped);
           }
         }
      });

      map.getOverlays().add(poiOverlay);
    }

    @Override
    public boolean isRouteDisplayed() {
      return false;
    }
   }

 

 

 

Routing

The following is a basic sample of displaying a route on the map using RouteManager. Please refer to the samples download for more advanced use cases.

 

 

Allow Internet access to your application in the AndroidManifest.xml and update the XML layout to allow interactivity. Refer back to the Basic Map sample for further details.

  <uses-permission android:name="android.permission.INTERNET"/>

 

  android:id="@+id/map"
  android:clickable="true"
  android:apiKey="YOUR_APPKEY_HERE"

 

Set your map and use RouteManager to add both the route ribbon and route locations in the .java file. Organize imports as needed (Ctrl+Shift+O).

  public class MyRouteMap extends MapActivity {
    protected MapView map;

    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);
      setupMapView();
      displayRoute();
    }

    // set your map and enable default zoom controls 
    private void setupMapView() {
      this.map = (MapView) findViewById(R.id.map);
      map.setBuiltInZoomControls(true);
    }

    // create a route and display on the map 
    private void displayRoute() {
      RouteManager routeManager = new RouteManager(this);
      routeManager.setMapView(map);
      routeManager.createRoute("San Francisco, CA", "Fremont, CA");
    }

    @Override
    public boolean isRouteDisplayed() {
      return true;
    }
  }

 

 

 

Route Narrative

The following allows you to display just the route narrative without the map.

 

 

Allow Internet access to your application in the AndroidManifest.xml. Refer back to the Basic Map sample for further details.

  <uses-permission android:name="android.permission.INTERNET"/>

 

Place the contents of the route narrative in a WebView layout.

  <?xml version="1.0" encoding="utf-8"?>

  <WebView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/itinerary"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
  />

 

Create route and display the narrative using RouteManager in the .java file. Note we are not extending MapActivity as no map is being shown in this application. Organize imports as needed (Ctrl+Shift+O).

  public class MyRouteNarrative extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

      WebView itinerary = (WebView) findViewById(R.id.itinerary);

      // pass in your AppKey to RouteManager when not extending MapActivity 
      RouteManager routeManager = new RouteManager(this,"YOUR_KEY_HERE");

      // generate and display the route narrative (itinerary) 
      routeManager.setItineraryView(itinerary);
      routeManager.createRoute("San Francisco, CA", "Fremont, CA");
    }
  }

 

 

 

Rotating the Map

The following is a basic sample showcasing the ability to change the orientation of the map.

 

 

Only one additional line of code is needed on top of the Basic Map sample to make this happen. Insert the following line:

  // specify the map's rotation in degrees 
  map.getController().setMapRotation(45);

 

While this is map rotation in its simplest form, combining it with the MyLocationOverlay class seen in the Finding Your Location sample can help you develop an application where the map display rotates as the orientation of the phone is changed.