To get started, you need to first create an Android project so that you can display the Google Maps in your activity.

codefile LBS.zip available for download at Wrox.com

Beginning with the Android SDK release v1.0, you need to apply for a free Google Maps API key before you can integrate Google Maps into your Android application. When you apply for the key, you must also agree to Google's terms of use, so be sure to read them carefully.

To apply for a key, follow the series of steps outlined next.

First, if you are testing the application on the Android Emulator or an Android device directly connected to your development machine, locate the SDK debug certificate located in the default folder (C:Users<username>.android for Windows 7 users). You can verify the existence of the debug certificate by going to Eclipse and selecting Window

Figure 9-3. FIGURE 9-3

The filename of the debug keystore is debug.keystore. This is the certificate that Eclipse uses to sign your application so that it may be run on the Android Emulator or devices.

Using the debug keystore, you need to extract its MD5 fingerprint using the Keytool.exe application included with your JDK installation. This fingerprint is needed to apply for the free Google Maps key. You can usually find the Keytool.exe in the C:Program FilesJava<JDK_version_number>in folder.

Issue the following command (see Figure 9-4) to extract the MD5 fingerprint:

keytool.exe -list -alias androiddebugkey -keystore
"C:Users<username>.androiddebug.keystore" -storepass android
-keypass android

Figure 9-4. FIGURE 9-4

In this example, my MD5 fingerprint is EF:7A:61:EA:AF:E0:B4:2D:FD:43:5E:1D:26:04:34:BA.

Copy the MD5 certificate fingerprint and navigate your web browser to: http://code.google.com/android/maps-api-signup.html. Follow the instructions on the page to complete the application and obtain the Google Maps key. When you are done, you should see something similar to what is shown in Figure 9-5.

Figure 9-5. FIGURE 9-5

You are now ready to display Google Maps in your Android application. This involves two main tasks:

The following Try It Out shows you how.

<uses-library android:name="com.google.android.maps" />

The previous section showed how you can display Google Maps in your Android application. You can pan the map to any desired location and it will be updated on-the-fly. However, on the emulator there is no way to zoom in or out from a particular location (on a real Android device you can pinch the map to zoom it). Thus, in this section, you will learn how you can let users zoom in or out of the map using the built-in zoom controls.

mapView = (MapView) findViewById(R.id.mapView);
        mapView.setBuiltInZoomControls(true);

Besides displaying the zoom controls, you can also programmatically zoom in or out of the map using the zoomIn() or zoomOut() method of the MapController class. The following Try It Out shows you how to achieve this.

public boolean onKeyDown(int keyCode, KeyEvent event)
{
    //...
}

By default, Google Maps is displayed in map view, which is basically drawings of streets and places of interest. You can also set Google Maps to display in satellite view using the setSatellite() method of the MapView class:

@Override
public void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);
     setContentView(R.layout.main);

     mapView = (MapView) findViewById(R.id.mapView);
     mapView.setBuiltInZoomControls(true);
     mapView.setSatellite(true);
}

Figure 9-8 shows Google Maps displayed in satellite view.

Figure 9-8. FIGURE 9-8

Besides satellite view, you can also display the map in street view (which highlights all the streets on the map) using the setStreetView() method. Figure 9-9 shows the map displaying a location in both street view (left) and satellite view (right).

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

    mapView = (MapView) findViewById(R.id.mapView);
    mapView.setBuiltInZoomControls(true);
    mapView.setSatellite(true);
    mapView.setStreetView(true);
}

If you want to display traffic conditions on the map, use the setTraffic() method

mapView.setTraffic(true);

Figure 9-9. FIGURE 9-9

Figure 9-10 shows the map displaying the current traffic conditions. The different colors reflect the varying traffic conditions. In general, green color equates to smooth traffic of about 50 miles per hour, yellow equates to moderate traffic of about 25-50 miles per hour, and red equates to slow traffic of about less than 25 miles per hour.

Figure 9-10. FIGURE 9-10

Note that the traffic information is only available in major cities in the United States, France, Britain, Australia, and Canada, with new cities and countries frequently added.

By default, Google Maps displays the map of the United States when it is first loaded. However, you can also set Google Maps to display a particular location. In this case, you can use the animateTo() method of the MapController class.

The following Try It Out shows how you can programmatically animate Google Maps to a particular location.

Adding markers to a map to indicate places of interest enables your users to easily locate the places they are looking for. The following Try It Out shows you how to add a marker to Google Maps.

TRY IT OUT: Adding Markers to the Map

1. Create a GIF image containing a pushpin (see Figure 9-12) and copy it into the res/drawable-mdpi folder of the project. For the best effect, make the background of the image transparent so that it does not block parts of the map when the image is added to the map.

   

   Figure 9-12. FIGURE 9-12

2. Using the project created in the previous activity, add the following statements in bold to the MainActivity.java file:

   package net.learn2develop.LBS;
   
   import android.app.Activity;
   
   import android.os.Bundle;
   import android.view.KeyEvent;
   
   import com.google.android.maps.GeoPoint;
   import com.google.android.maps.MapActivity;
   import com.google.android.maps.MapController;
   import com.google.android.maps.MapView;
   
   import android.graphics.Bitmap;
   import android.graphics.BitmapFactory;
   import android.graphics.Canvas;
   import android.graphics.Point;
   import com.google.android.maps.Overlay;
   import java.util.List;
   
   public class MainActivity extends MapActivity {
       MapView mapView;
       MapController mc;
       GeoPoint p;
   
       class MapOverlay extends com.google.android.maps.Overlay
       {
           @Override

   public booleandraw(Canvas canvas, MapView mapView,
           boolean shadow, long when)
           {
               super.draw(canvas, mapView, shadow);
   
               //---translate the GeoPoint to screen pixels---
               Point screenPts = newPoint();
               mapView.getProjection().toPixels(p, screenPts);
   
               //---add the marker---
               Bitmap bmp = BitmapFactory.decodeResource(
                   getResources(), R.drawable.pushpin);
               canvas.drawBitmap(bmp, screenPts.x, screenPts.y-50, null);
               return true;
           }
   }
   
       /** Called when the activity is first created. */
       @Override
       public void onCreate(Bundle savedInstanceState) {
           super.onCreate(savedInstanceState);
           setContentView(R.layout.main);
   
           mapView = (MapView) findViewById(R.id.mapView);
           mapView.setBuiltInZoomControls(true);
   
           //mapView.setSatellite(true);
           //mapView.setStreetView(true);
   
           mc = mapView.getController();
           String coordinates[] = {"1.352566007", "103.78921587"};
           double lat = Double.parseDouble(coordinates[0]);
           double lng = Double.parseDouble(coordinates[1]);
   
           p = new GeoPoint(
               (int) (lat * 1E6),
               (int) (lng * 1E6));
   
           mc.animateTo(p);
           mc.setZoom(13);
   
           //---Add a location marker---
           MapOverlay mapOverlay = newMapOverlay();
           List<Overlay> listOfOverlays = mapView.getOverlays();
           listOfOverlays.clear();
           listOfOverlays.add(mapOverlay);
   
           mapView.invalidate();
       }
   
       public boolean onKeyDown(int keyCode, KeyEvent event)
       {
           MapController mc = mapView.getController();
           switch (keyCode)

   {
               case KeyEvent.KEYCODE_3:
                   mc.zoomIn();
                   break;
               case KeyEvent.KEYCODE_1:
                   mc.zoomOut();
                   break;
           }
           return super.onKeyDown(keyCode, event);
       }
       @Override
       protected boolean isRouteDisplayed() {
           // TODO Auto-generated method stub
           return false;
       }
   }

3. Press F11 to debug the application on the Android Emulator. Figure 9-13 shows the marker added to the map.

   

   Figure 9-13. FIGURE 9-13

How It Works

To add a marker to the map, you first need to define a class that extends the Overlay class:

class MapOverlay extends com.google.android.maps.Overlay
{
    @Override
    public boolean draw(Canvas canvas, MapView mapView,

boolean shadow, long when)
     {
         //...
     }
}

An overlay represents an individual item that you can draw on the map. You can add as many overlays as you want. In the MapOverlay class, override the draw() method so that you can draw the pushpin image on the map. In particular, note that you need to translate the geographical location (represented by a GeoPoint object, p) into screen coordinates:

//---translate the GeoPoint to screen pixels---
Point screenPts = new Point();
mapView.getProjection().toPixels(p, screenPts);

Because you want the pointed tip of the pushpin to indicate the position of the location, you need to deduct the height of the image (which is 50 pixels) from the y coordinate of the point (see Figure 9-14) and draw the image at that location:

//---add the marker---
Bitmap bmp = BitmapFactory.decodeResource(
    getResources(), R.drawable.pushpin);
canvas.drawBitmap(bmp, screenPts.x, screenPts.y-50, null);

Figure 9-14. FIGURE 9-14

To add the marker, create an instance of the MapOverlay class and add it to the list of overlays available on the MapView object:

//---Add a location marker---
MapOverlay mapOverlay = new MapOverlay();
List<Overlay> listOfOverlays = mapView.getOverlays();
listOfOverlays.clear();
listOfOverlays.add(mapOverlay);

After using Google Maps for a while, you may want to know the latitude and longitude of a location corresponding to the position on the screen that was just touched. Knowing this information is very useful, as you can determine a location's address, a process known as reverse geocoding (you will learn how this is done in the next section).

If you have added an overlay to the map, you can override the onTouchEvent() method within the MapOverlay class. This method is fired every time the user touches the map. This method has two parameters: MotionEvent and MapView. Using the MotionEvent parameter, you can determine whether the user has lifted his or her finger from the screen using the getAction() method. In the following code snippet, if the user has touched and then lifted the finger, you display the latitude and longitude of the location touched:

import android.view.MotionEvent;
import android.widget.Toast;
//...

    class MapOverlay extends com.google.android.maps.Overlay
    {
        @Override
        public boolean draw(Canvas canvas, MapView mapView,
        boolean shadow, long when)
        {
            super.draw(canvas, mapView, shadow);

            //---translate the GeoPoint to screen pixels---
            Point screenPts = new Point();
            mapView.getProjection().toPixels(p, screenPts);

            //---add the marker---
            Bitmap bmp = BitmapFactory.decodeResource(
                getResources(), R.drawable.pushpin);
            canvas.drawBitmap(bmp, screenPts.x, screenPts.y-50, null);
            return true;
        }

        @Override
        public boolean onTouchEvent(MotionEvent event, MapView mapView)
        {
            //---when user lifts his finger---
            if(event.getAction() == 1) {
               GeoPoint p = mapView.getProjection().fromPixels(
                   (int) event.getX(),
                   (int) event.getY());
                   Toast.makeText(getBaseContext(),
                       "Location: "+
                       p.getLatitudeE6() / 1E6 + ","+
                       p.getLongitudeE6() /1E6 ,
                       Toast.LENGTH_SHORT).show();
            }
            return false;
       }
}

The getProjection() method returns a projection for converting between screen-pixel coordinates and latitude/longitude coordinates. The fromPixels() method then converts the screen coordinates into a GeoPoint object.

Figure 9-15 shows the map displaying a set of coordinates when the user clicks a location on the map.

Figure 9-15. FIGURE 9-15

As mentioned in the preceding section, if you know the latitude and longitude of a location, you can find out its address using a process known as reverse geocoding. Google Maps in Android supports this via the Geocoder class. The following code snippet shows how you can retrieve the address of a location just touched using the getFromLocation() method:

import android.location.Address;
import android.location.Geocoder;
import java.util.Locale;
import java.io.IOException;
//...

        @Override
        public boolean onTouchEvent(MotionEvent event, MapView mapView)
        {
            //---when user lifts his finger---
            if (event.getAction() == 1) {
                GeoPoint p = mapView.getProjection().fromPixels(
                    (int) event.getX(),
                    (int) event.getY());
                    /*
                    Toast.makeText(getBaseContext(),
                        "Location: "+
                        p.getLatitudeE6() / 1E6 + "," +
                        p.getLongitudeE6() /1E6 ,
                        Toast.LENGTH_SHORT).show();

*/

                Geocoder geoCoder = newGeocoder(
                    getBaseContext(), Locale.getDefault());
                try {
                    List<Address> addresses = geoCoder.getFromLocation(
                        p.getLatitudeE6()  / 1E6,
                        p.getLongitudeE6() / 1E6, 1);

                    String add = "";
                    if(addresses.size() > 0)
                    {
                        for(inti=0; i<addresses.get(0).getMaxAddressLineIndex();
                             i++)
                           add += addresses.get(0).getAddressLine(i) + "
";
                    }
                    Toast.makeText(getBaseContext(), add, Toast.LENGTH_SHORT).show();
                }
                catch(IOException e) {
                    e.printStackTrace();
                }
                return true;
        }
        return false;
    }
}

The Geocoder object converts the latitude and longitude into an address using the getFromLocation() method. Once the address is obtained, you display it using the Toast class. Figure 9-16 shows the application displaying the address of a location that was touched on the map.

If you know the address of a location but want to know its latitude and longitude, you can do so via geocoding. Again, you can use the Geocoder class for this purpose. The following code shows how you can find the exact location of the Empire State Building by using the getFromLocationName() method:

//---geo-coding---
Geocoder geoCoder = new Geocoder(this, Locale.getDefault());
try {
    List<Address> addresses = geoCoder.getFromLocationName(
        "empire state building", 5);

    String add = "";
    if(addresses.size() > 0) {
       p = new GeoPoint(
              (int) (addresses.get(0).getLatitude() * 1E6),
              (int) (addresses.get(0).getLongitude() * 1E6));
       mc.animateTo(p);
       mapView.invalidate();
    }
} catch(IOException e) {
            e.printStackTrace();
        }

Figure 9-17 shows the map navigating to the location of the Empire State Building.

Figure 9-16. FIGURE 9-16

Figure 9-17. FIGURE 9-17

One very cool feature of the LocationManager class is its ability to monitor a specific location. This is achieved using the addProximityAlert() method. The following code snippet shows how to monitor a particular location so that if the user is within a five-meter radius from that location, your application will fire an intent to launch the web browser:

//---use the LocationManager class to obtain locations data---
lm = (LocationManager)
     getSystemService(Context.LOCATION_SERVICE);

//---PendingIntent to launch activity if the user is within some locations---
PendingIntent pendIntent = PendingIntent.getActivity(
    this, 0, new
    Intent(android.content.Intent.ACTION_VIEW,
      Uri.parse("http://www.amazon.com")), 0);

lm.addProximityAlert(37.422006, −122.084095, 5, −1, pendIntent);

The addProximityAlert() method takes five arguments: latitude, longitude, radius (in meters), expiration (time for the proximity alert to be valid, after which it will be deleted; −1 for no expiration), and the pending intent.

Note that if the Android device's screen goes to sleep, the proximity is also checked once every four minutes in order to preserve the battery life of the device.