Understanding the Amazon Maps API

Introduction

With the Amazon Maps API, you can quickly and easily create a mapping application for Kindle Fire tablets. The Maps API includes features that allow you to:

  • Display location data.
  • Handle user interaction with maps.
  • Apply location-based map markers.

Once your app is registered, it automatically downloads map tiles. See Building and Testing Your Maps App for information on the registration process.

Note: Kindle Fire (1st Generation) does not support the Maps API.

This guide provides an overview of programming with the Amazon Maps API. For further information, see:

Note: All classes in the Amazon Maps API are members of the package com.amazon.geo.maps.


Displaying an Interactive Map

With very little effort, your app can use the Amazon Maps API to display a map that the user can pan and zoom. The map's default behavior is to handle user interaction in response to touch input. All you do is subclass MapActivity and provide the subclass with a reference to the layout View for the map.

The simplest way to set up the map's View (that is, its MapView) is to define it in the XML file that specifies your app's layout, as shown below:

<com.amazon.geo.maps.MapView
   android:id="@+id/mapview"
   android:layout_width="fill_parent"
   android:layout_height="fill_parent"
   android:enabled="true"
   android:clickable="true"
/>

Note: The other way to define a MapView is to use one of the MapView constructors. You would then add the MapView to a layout View with ViewGroup.addView(View).

The following code demonstrates supplying a main.xml layout file to MapActivity to set up the map:

// MapActivity provides basic lifecycle management and window creation for your map.

public class CoffeeActivity extends MapActivity {

   @Override

   public void onCreate(final Bundle bundle) {

      super.onCreate(bundle);

      // Provide setContentView a reference to the XML layout file for your app;
      // the file should contain a MapView element.
      setContentView(R.layout.main);

   }

   @Override

   // Calling isRouteDisplayed is required, but it exists for interface compatibility
   // with the Google Maps External Library only. Recommend setting to false.
   protected boolean isRouteDisplayed() {
      return false;
   }
}


Controlling the Map's Center and Zoom Level

Your app can directly set the map's center, as well as its zoom level (scale), by using the MapController class. In the code below, the map is set to show a neighborhood in Seattle:

public class CoffeeActivity extends MapActivity {

...

   @Override

      public void onCreate(final Bundle bundle) {

         ...
 
         // You must obtain a reference to the map view, in order to work with it.
         mMapView = (MapView) findViewById(R.id.mapview);

         // Now you can obtain a reference to the map controller.
         mMapController = mMapView.getController();

         // The GeoPoint type represents a coordinate's latitude and longitude in microdegrees;
         // that is, a number of standard coordinate degrees multiplied by one million.
         final GeoPoint capitolHillLocation = new GeoPoint(47620079, -122320926);

         // This sets the map center to the fixed GeoPoint we've defined above.
         mMapController.setCenter(capitolHillLocation);

         // Zoom in sufficiently to display individual businesses.
         mMapController.setZoom(17);

   }

    ...

}


Marking Locations on the Map

A common use for maps is to indicate points of interest with visual overlays. For example, your app may use a map to indicate the user's current location or that of restaurants or homes for sale.

The Amazon Maps API provides a number of related classes to create and manage these overlays:

  • MyLocationOverlay - a special-use class for displaying the user's current location
  • ItemizedOverlay - a type of overlay that creates a list of overlay items and manages user interaction with them
  • OverlayItem - a single member of an ItemizedOverlay list, defined by fields containing a location point, an image, and text for the item

This sample demonstrates using maps to display the user's location and that of the coffee shops in a given area:

public class CoffeeActivity extends MapActivity {

   ...

   @Override

      public void onCreate(final Bundle bundle) {

         ...

         // Define an overlay for the user's current location.
          mLocationOverlay = new MyLocationOverlay(this, mMapView);

         // Get the map's overlay list and add the user's location overlay to it.
         mMapView.getOverlays().add(mLocationOverlay);

         // If the user has turned on location services for their device, when you
         // call enableMyLocation, the user's location is tracked and displayed.
         // Note that if you are testing your app on a device emulator, rather than an actual device,
         // the enableMyLocation method does not automatically return the current location.
         mLocationOverlay.enableMyLocation();

         // Obtain the image to use to indicate coffee shops on the map.
         final Drawable coffeeMarker = this.getResources().getDrawable(R.drawable.coffeemarker);

         // Add the image to CoffeeOverlay, an ItemizedOverlay containing a list of coffee shops.
         mCoffeeOverlay = new CoffeeOverlay(coffeeMarker);

         // Add the ItemizedOverlay of coffee shops to the map's overlay list.
         mMapView.getOverlays().add(mCoffeeOverlay);

         // Display the ItemizedOverlay indicating the coffee shops in a given area of interest.
         mCoffeeOverlay.update(mMapView.getMapCenter(), mMapView.getZoomLevel());

     }

     ...

}

Figure 1: Displaying an ItemizedOverlay of coffee shop locations


Next Steps

Beyond these basic tasks, see the CapitolHillCoffee sample app for an example of adding a popup window that provides details on the corresponding coffee shop when the user touches its item in the overlay. The CapitolHillCoffee sample is part of the Amazon Mobile App SDK.

For information on setting up your build environment to use the Amazon Maps API, as well as testing guidelines, see Building and Testing Your Maps App.

You can also look at the Frequently Asked Questions to see how to use the Amazon Maps API, if you already support Google Maps.

The Amazon Maps API makes it quick and easy to add mapping functionality to your app. It's up to you what direction to take.


Return to the Amazon Maps API

Unavailable During Maintenance